ServBay PHP Configuration Guide: Adjusting php.ini, PHP-FPM, and Extension Modules

ServBay offers web developers a powerful and flexible local PHP development environment. To meet the unique requirements of different projects, you might need to tweak various PHP settings, such as memory limits, file upload sizes, error reporting levels, or enabling specific extension modules.

This article provides a step-by-step guide on modifying PHP configurations within ServBay. While it's useful to know the locations and structure of underlying configuration files like php.ini and php-fpm.conf, it is highly recommended to use ServBay’s built-in user interface (UI) for any changes to ensure those modifications are persistent and compatible.

Important Notice

Do not manually edit the PHP configuration files generated by ServBay (located in /Applications/ServBay/etc/php/<version>/ and its subdirectories). These files are managed by ServBay, and manual changes will be overwritten whenever ServBay is updated, restarted, or during other maintenance operations. All PHP configurations should be managed through ServBay’s user interface.

Overview

In ServBay, configuration files for each PHP version are stored in separate directories. For example, the main configuration files for PHP 8.3 are located in /Applications/ServBay/etc/php/8.3.

The core configuration files include:

• php.ini: The main configuration file for PHP, affecting both CLI and web environments.
• php-fpm.conf: The configuration file for PHP-FPM (FastCGI Process Manager), mainly influencing how PHP runs and performs under web servers such as Caddy or Nginx.
• conf.d/: This directory contains loader configuration files (.ini) for individual PHP extensions, for example, xdebug.ini, opcache.ini, etc.

While these files exist, ServBay provides a much safer and more convenient way to tweak their parameters.

Configure PHP Through the ServBay User Interface (Recommended)

ServBay offers an intuitive graphical interface that allows you to directly modify various PHP configuration parameters. Whenever you save changes through the UI, ServBay automatically applies them and will restart the PHP service if necessary—usually without any manual intervention or command-line operations.

To access PHP configuration options:

1. Open the main ServBay window.
2. In the left navigation bar, click Languages.
3. From the list of supported development languages, locate and select the PHP version you want to configure (e.g., click PHP 8.3).
4. The right panel will display the details and configuration options for that PHP version.

A typical PHP configuration interface looks like this:

The interface is usually divided into three main sections: PHP-FPM, PHP (php.ini), and PHP extension module configurations. Each is described below.

PHP-FPM Configuration

Tip

Settings in php-fpm.conf primarily affect how PHP behaves in a web server environment. Any parameters set in this section via ServBay UI take precedence over the corresponding settings in php.ini, but only apply to web requests. These settings do not affect PHP when used from the command line (CLI).

ServBay’s web services (Caddy or Nginx) interact with PHP through PHP-FPM. The PHP-FPM configuration interface lets you adjust parameters that impact web environment performance and stability, such as:

• Process management (pm): Controls how PHP-FPM spawns and manages worker processes (e.g., dynamic, static).
• Process count (pm.max_children, pm.start_servers, etc.): Sets max child processes, the number of workers started initially, and more—important for concurrency.
• Memory limit (memory_limit): This setting here overrides the one in php.ini for web requests only.
• Error logging and display: Configure error log paths, error levels, and whether errors should be shown in the browser.

For example, if you want to increase PHP’s memory limit for web use from the default (such as 64M or 128M) to 1G, simply find the memory_limit option in the PHP-FPM section, select 1G from the dropdown, and click Save. This change will affect only scripts run via the web server; CLI scripts will still obey the memory_limit value in php.ini.

Example comparison: If memory_limit in php.ini is set to 512M, but to 128M in PHP-FPM config:

• Running PHP scripts via CLI, the memory limit is 512M.
• Accessing PHP scripts via the web, the memory limit is 128M.

php.ini Configuration

Tip

Settings in php.ini are global—they affect both CLI and web environments. As discussed above, values set in PHP-FPM will override the same settings from php.ini for web requests.

The PHP configuration section in the ServBay UI corresponds to the main options in php.ini. Here, you can adjust many common PHP runtime parameters, such as:

• post_max_size: Maximum size for data sent via POST.
• upload_max_filesize: Maximum allowed file size for uploads.
• date.timezone: Default timezone for PHP.
• display_errors / error_reporting: Controls whether errors are shown in the browser and which error levels are reported.
• max_execution_time: The maximum permitted runtime for scripts (in seconds).
• disable_functions / disable_classes: Disable certain PHP functions or classes for enhanced security.
• open_basedir: Restricts filesystem paths accessible by PHP. For convenience and security, it is recommended to store all web projects under ServBay’s default web root directory /Applications/ServBay/www, so you can specify this single directory for open_basedir instead of multiple paths.

You can easily make these changes to common php.ini options directly through ServBay's UI.

For details on all php.ini configuration options, consult the official PHP documentation: PHP Runtime Configuration.

PHP Extension Modules Configuration

ServBay comes pre-packaged with a wide variety of popular PHP extensions, covering everything from database connectivity and caching to debugging and framework support. The ServBay UI offers an easy way to enable or disable these modules and configure their specific parameters.

Some commonly supported extensions include but are not limited to xDebug, OPcache, ImageMagick, Redis, MongoDB, Phalcon, Swoole, and more. ServBay also supports additional integrations for various databases (MySQL, PostgreSQL, MongoDB), message queues, caching systems, etc.

Enabling or disabling PHP extensions is very straightforward:

1. In the PHP configuration interface in ServBay UI, switch to the "Extensions" tab (or similar label).
2. Locate the extension module you need (e.g., xdebug).
3. Use the toggle button to enable or disable it.
4. For extensions with additional parameters (such as xDebug), you can configure options like xdebug.mode, xdebug.client_port, and more directly in the interface.
5. Click the Save button to apply changes.

For a full list and more details on all supported PHP extension modules, refer to the PHP Extension Modules List in the official ServBay documentation (make sure to view the latest version).

Understanding PHP Configuration File Structure (Manual Editing Not Recommended)

While using the ServBay UI is strongly recommended for all configuration changes, understanding the location and structure of underlying configuration files can help you better understand how PHP runs behind the scenes.

ServBay generates PHP configuration files under /Applications/ServBay/etc/php/<version>/.

• php.ini: Main configuration file.
• php-fpm.conf: PHP-FPM process manager configuration.
• conf.d/: Directory containing .ini files for individual extensions.

Sample php.ini File Structure

The php.ini file uses the INI file format. Here are sample versions of some common configuration entries:

; Change memory limit
memory_limit = 256M

; Change file upload size limits
upload_max_filesize = 50M
post_max_size = 50M

; Set timezone
date.timezone = "Asia/Shanghai" ; or "UTC", "America/New_York", etc. Set as appropriate.

; Enable error display (for development only!)
display_errors = On
error_reporting = E_ALL

; Set maximum execution time
max_execution_time = 300

; Restrict allowed filesystem paths (example)
; open_basedir = /Applications/ServBay/www/:/tmp/

Sample php-fpm.conf File Structure

The php-fpm.conf file contains both global settings and pool (process) settings. ServBay typically configures a default pool called www.

[global]
; Path to global error log
error_log = /Applications/ServBay/logs/php/8.3/errors.log

[www]
; Address and port or socket file for listening
listen = /Applications/ServBay/tmp/php-cgi-8.3.sock
listen.backlog = -1
listen.allowed_clients = 127.0.0.1

; User and group (ServBay typically runs as the current user)
; user = servbay-demo
; group = staff

; Process management mode (static, dynamic, ondemand)
pm = dynamic
pm.max_children = 10       ; Maximum child processes
pm.start_servers = 2       ; Number of processes created on start
pm.min_spare_servers = 1   ; Minimum number of idle child processes
pm.max_spare_servers = 6   ; Maximum number of idle child processes
pm.max_requests = 1024     ; Max requests per child, trigger restart to avoid memory leaks

; Enable slow log (records requests taking longer than request_slowlog_timeout)
request_slowlog_timeout = 5s
slowlog = /Applications/ServBay/logs/php/8.3/slow.log

; PHP settings that override php.ini (examples)
; php_admin_value[memory_limit] = 128M
; php_admin_flag[display_errors] = on

PHP Module Loader Configuration Example (conf.d/)

.ini files in the conf.d/ directory are used for loading and configuring specific PHP extensions. For example, the xdebug.ini file might contain:

[Xdebug]
; Load the Xdebug extension
zend_extension = xdebug.so

; Xdebug modes (debug, develop, profile, trace, coverage)
xdebug.mode=debug,develop

; How to trigger debugging (yes, trigger, develop)
; yes: always enable debugging
; trigger: enable when specific GET/POST param or cookie is set
; develop: developer mode only (features like stack traces)
xdebug.start_with_request=yes

; Client host and port for IDE connection
xdebug.client_host=localhost
xdebug.client_port=39083

; Xdebug log path
xdebug.log=/Applications/ServBay/logs/xdebug/8.3/xdebug.log

Once again: while you can browse these files, do not edit them directly. Always use the ServBay UI for configuration.

Applying Changes: Restarting PHP Services

After making changes in the ServBay UI, ServBay will usually automatically detect and apply the updates. In some cases, you may need to restart the relevant PHP service to ensure all changes take effect.

You can restart the PHP service as follows:

Restarting via ServBay User Interface

1. Open the main ServBay window.
2. In the left navigation bar, click Packages.
3. Find the PHP version whose configuration you have modified.
4. Click the restart button (usually a circular arrow icon) next to that PHP version.

Restarting via servbayctl Command Line Tool

For developers who prefer the command line, ServBay provides the servbayctl tool for managing services, including restarting a specific version of PHP.

Open your terminal and run the following command (replace 8.3 with the PHP version you need to restart):

servbayctl restart php 8.3

After running this command, ServBay will restart the specified PHP-FPM process, making the new configuration active.

Frequently Asked Questions (FAQ)

• Q: I manually edited the php.ini file, but my changes aren’t taking effect or are getting reverted. Why?

  • A: ServBay manages and generates configuration files for its packages. Any manual edits may be overwritten whenever ServBay updates, restarts services, or performs internal operations. Always use the ServBay UI to modify PHP settings for persistence and reliability.

• Q: How do I increase PHP’s memory limit or upload file size?

  • A: Open the ServBay UI, navigate to Languages → select your PHP version. In the PHP-FPM config section, adjust memory_limit (affects web). In the php.ini config section, modify upload_max_filesize and post_max_size (affects all; web may be overridden by FPM settings). Save and restart PHP as needed.

• Q: How do I enable or configure Xdebug?

  • A: Open the ServBay UI, go to Languages → select your PHP version. In the Extensions section, locate xdebug, enable it, and adjust parameters such as xdebug.mode, xdebug.client_host, xdebug.client_port, etc., according to your IDE and debugging needs. Save and restart PHP.

• Q: What’s the difference between php.ini and PHP-FPM configuration? Which one should I change?

  • A: php.ini is the global configuration for PHP, affecting both CLI and web. PHP-FPM config (php-fpm.conf) is specific to how PHP runs under a web server, and duplicate settings here will override their php.ini counterparts for web requests. For web-specific settings (like memory limits, execution time, error display), prioritize PHP-FPM; for CLI or global settings (like timezone, disabled functions), use php.ini. ServBay's UI clearly separates these options.

Summary

ServBay’s user interface provides a safe and convenient way to manage all of your PHP configuration—including php.ini, PHP-FPM, and various extension modules. Making adjustments through the UI and restarting the PHP service as needed ensures your development environment is always correctly set up for your work. While understanding the underlying file structure is useful, always use the ServBay UI for actual changes to prevent your edits from getting overwritten. Leverage ServBay’s powerful configuration capabilities to easily tailor your PHP environment for any project.