Customize Web Server and PHP Environment

PHP has a built-in Web Server, but it is only suitable for debug. In a production environment, we recommend that you use Procfile to describe the Web Server used by PHP. Of course, if your code does not include Procfile, we will prompt you in the Create Application Wizard Choose a Web Server.

This document introduces how to customize Web Server through Procfile, and how to specify custom Web Server configuration and PHP configuration.

1. Customize Web Server

Gridworkz uses the compatible heroku/heroku-buildpack-php to build the PHP runtime environment, which includes the use of scripts to start PHP or HHVM Program and automatically associate with Apache or Nginx.

Available startup script commands and meanings:

Start script nameDescription
heroku-php-apache2PHP & Apache2
heroku-php-nginx​​PHP & Nginx

These scripts will be installed in the vendor/bin directory of the code root directory when building the PHP environment, so when choosing to use different startup scripts, you need to specify the complete execution directory, such as: vendor/bin/heroku-php-apache2

The following describes how to customize Web Server in the Procfile file:

1.1 Nginx+PHP

web: vendor/bin/heroku-php-nginx

1.2 Apache+PHP

web: vendor/bin/heroku-php-apache2

1.3 Apache+HHVM

web: vendor/bin/heroku-hhvm-apache2

1.4 Set Document Root

Many users' applications do not use the code and directory as the home directory of the Web Server. For example, programs written using the popular PHP framework Laravel require the Document root to be the public directory.

The following example uses Apache and PHP, and the Document root is set to the /public secondary directory in the following directory, then your Procfile file should be written like this:

web: vendor/bin/heroku-php-apache2 public/

If other additional options are specified in the startup script (rewrite rules are specified in the following example), you need to ensure that the document root parameter is placed at the end of all parameter commands. If your code root directory is Document root, it is simple, just omit the setting of Document root, as follows:

web: vendor/bin/heroku-php-apache2

1.5 Apache Default Configuration

Apache uses a virtual host to match all host names. Similar options are as follows:

<Directory "${DOCUMENT_ROOT}">
    Options FollowSymLinks

    # allow .htaccess to do everything
    AllowOverride All

    # no limits
    Require all granted

All files ending in .php will be routed to PHP-FPM and processed through fcgi://heroku-fcgi. The DirectoryIndex property is set to index.php, index.html, index.html.

1.6 Nginx Default Configuration

Nginx uses a virtual host to match all host names. The document root does not have any access restrictions. All files ending with .php will be routed to PHP-FPM for processing through fcgi://heroku-fcgi. The DirectoryIndex property is set to index.php, index.html, index.html. A similar Nginx configuration is as follows:

upstream php-fpm {
    server unix:/tmp/php-fpm.sock max_fails=3 fail_timeout=3s;
    keepalive 16;

server {
    location @php-fcgi {
        fastcgi_pass php-fcgi;

    # Process all .php files
    location ~ \.php {
        try_files @php-fcgi @php-fcgi;

1.7 Web Server Settings

Users can customize the configuration of Apache or Nginx according to their site needs.

1.7.1 Apache Configuration

Users can define ordinary .htaccess files to customize the behavior of Apache HTTP server. As mentioned above, the AllowOverride option of the document root directory is fully enabled by default, so the user configures the .htaccess file and the Apache Web server will automatically load the configuration.

We recommend this method to customize the Web Server. Of course, in addition to this method, we also support the traditional apache configuration file to customize the configuration. You only need to create a configuration file in the code root directory (such as: apache_app.conf ) Can be as follows:

RewriteEngine On

RewriteCond %{REQUEST_URI}::$1 ^(/.+)/(.*)::\2$
RewriteRule ^(.*)-[E=BASE:%1]

RewriteRule ^app\.php(/(.*)|$) %{ENV:BASE}/$2 [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f
RewriteRule .?-[L]

RewriteRule .? %{ENV:BASE}/app.php [L]

Here we have configured some rewrite rules. After I added a new apache configuration file, I only need to add the -C parameter configuration in the startup description file Procfile to load the configuration file:

web: vendor/bin/heroku-php-apache2 -C apache_app.conf

1.7.2 Nginx Configuration

Nginx can load the customized configuration into the main configuration file through Include. For example, you can configure rewrite rules for your Symfony2 application by creating the nginx_app.conf file in the code root directory:

location / {
    # try to serve file directly, fallback to rewrite
    try_files $uri @rewriteapp;

location @rewriteapp {
    # rewrite all to app.php
    rewrite ^(.*)$ /app.php/$1 last;

location ~ ^/(app|app_dev|config)\.php(/|$) {
    try_files @heroku-fcgi @heroku-fcgi;

The internal option is to confirm that all requests to /app.php are through rewrite.

Similar to the custom Apache configuration, you finally need to specify the newly added configuration file through the -C parameter in the Procfile file:

web: vendor/bin/heroku-php-nginx -C nginx_app.conf

1.8 Default Behavior

PHP application running will start a FastCGI Process Manager (PHP-FPM) or HHVM application Server. The server accepts requests from Apache or Nginx and finally executes the PHP file.

1.9 Listening Port

The Web server listens to port 5000 by default, which is also the default port of all HTTP protocols on the platform. Users cannot modify this port. After the program is started, the platform will automatically map port 5000 to the load balancer, and the user type determines the final open port

2. Custom PHP Configuration

2.1 INI File Configuration

Gridworkz provides multiple ways to customize the configuration in php.ini.

  • Through ini_set in the PHP program;
  • Add a configuration file in PHP-FPM format to the source code and directory, and load it when starting the application through Procfile;
  • Add a .user.ini file in the root directory of the source code, and PHP-FPM will automatically load it when it starts;

Before the PHP program is executed, it will read the contents of the .user.ini file in its directory to set the corresponding parameters. Therefore, under normal circumstances, we only need to place the custom-configured .user.ini file in the code root directory. If your document root is another directory, please operate according to the actual situation.

Gridworkz recommends using .user.ini file to customize PHP settings. Please refer to PHP Documentation to set .user.ini correctly.


Don’t worry that this method will affect the performance of your program. By default, the time of user_ini.cache_ttl is 300 seconds. Of course you can also set this time longer

For example, if we change the maximum allowed upload file to 5 MB, you can put a .user.ini file in the document root directory with the following content:

upload_max_filesize = 5M

2.2 PHP-FPM Loading Configuration Method

There is a small part of PHP.ini configuration that cannot be set by .user.ini, such as always_populate_raw_post_data. In this case, it can only be achieved by setting PHP’s FastCGI process manager. For detailed usage, see PHP Manual.

For example, setting always_poplate_raw_post_data to -1 requires adding the fpm_custom.conf file in the root directory of the code, with the following content:


Of course, we still need to specify this configuration file through the Procfile file:

web: vendor/bin/heroku-php-nginx -F fpm_custom.conf public/

Setting PHP.ini through PHP-FPM has certain risks. If the parameter configuration is wrong, the PHP-FPM process will not run, and the application will fail to start. Therefore, it is best to test it locally before setting it, or from the application The reason for the startup failure is found in the log information.

2.3 Php Environment Concurrent Tuning

The PHP applications running on Gridworkz are managed by FastCGI process manager or HHVM engine. Communicate with Aapache or Nginx through FastCGI protocol

FPM creates and manages sub-processes to execute corresponding PHP code. Of course, HHVM uses threads to achieve the same purpose. At the same time, each process or thread processes a request (user request) from the web server, which means that more processing processes or threads can improve the concurrent processing capabilities of the application.

Memory limit in the PHP configuration is applied to each processing process, when the process memory reaches the line The process will be terminated.

3. Default Configuration and Behavior


PHP-FPM runs in a static process management mode by default, which means that it starts a certain number of processing processes at once when it starts. The number of processing processes can be dynamically adjusted in Gridworkz. The “Memory Adjustment” option on the advanced page can increase the number of processing processes while increasing a single instance. For the specific relationship between memory and processing processes, see the following list.

Instance memoryMaximum memory limit for a single processNumber of processes

The maximum memory limit of a single thread can be adjusted in the form of a configuration file. When the instance memory is unchanged, adjusting the single-process memory limit can increase the number of concurrency, but for large programs, it is recommended to use horizontal expansion to increase the number of instances. This can not only increase concurrency, but also distribute requests to each host to increase the number Service availability.

3.2 Set Single Process Memory Limit

3.2.1 Set by .user.ini File

Configure the settings in PHP.INI by creating a .user.ini file in the code root directory. The following example sets memory_limit to 8M:

# linux | mac
echo "memory_limit = 8M"> .user.ini
# windows
echo memory_limit = 8M> .user.ini

The memory size unit is M, please use uppercase

If the user code is no longer the root directory, you need to specify the location of the root directory in the Procfile, and then put .user.ini in the code root directory. Submit the code after modifying the file, and you will see the following log information when deploying the application:

Application ready for connections on port 5000.
Starting httpd...
Starting php-fpm...
16 processes at 8MB memory limit.
Optimizing php-fpm worker for 128M Memory....

Set through the attached fpm configuration file In addition to using the .user.ini file to customize the configuration, you can also use PHP-FPM Include to add configuration, and use the php_value or php_admin_value command to set the value of memory_limit. For example, to set the maximum memory of a single process to 64M, you can create a file named fpm_custom.conf with the following content:

php_value[memory_limit] = 64M

For this configuration to take effect, you also need to create a Procfile file in the code root directory, and specify it with the -F parameter, so that this custom configuration file can be loaded when php-fpm starts. The following is an example of the content of the Procfile file:

web: vendor/bin/heroku-php-apache2 -F fpm_custom.conf

Define the number of processes through the WEB_CONCURRENCY variable You can define the WEB_CONCURRENCY variable directly on the advanced page of the application. This variable is a numeric type and directly affects the number of processes in php-fpm.

Novice users are not recommended to use the WEB_CONCURRENCY variable to define the number of php-fpm processes. The concurrent processing capacity of the service is not only determined by the number of processes. If the memory of a single instance is too small, opening too many processes will reduce the processing capacity.

3.3 Custom Configuration Priority

WEB_CONCURRENCY —> fpm configuration file —>

From left to right priority from high to bottom

  • Adjusting the number of php-fpm processes alone does not necessarily increase the number of concurrency, and needs to be dynamically adjusted with the memory size of a single instance
  • The effect of horizontal expansion is better than the optimization effect of a single instance. It is recommended to open more instances
  • Please select a method of process adjustment, do not have multiple methods at the same time.