Last updated September 27, 2024

This document describes the general behavior of Heroku as it relates to the recognition and execution of PHP applications.

Activation

The Heroku PHP Support will be applied to applications only when the application has a file named composer.json in the root directory. Even if an application has no Composer dependencies, it must include at least an empty ({}) composer.json in order to be recognized as a PHP application.

When Heroku recognizes a PHP application, it will respond accordingly during a push:

$ git push heroku main
-----> PHP app detected
…

If composer.json specifies dependencies of any kind in its require section, the corresponding composer.lock that gets generated by running composer update must also be committed to the repository, or the push will be rejected. This ensures that the dependencies Heroku installs are exactly the same as in any other environment. Please refer to the “Manage Dependencies” section of the Deploying PHP guide for detailed instructions.

PHP runtimes

Heroku allows you to run your application using the official PHP runtime.

Supported versions

Heroku’s PHP support extends to applications using the latest available releases in the PHP 8.1, PHP 8.2, and PHP 8.3 series.

The support for PHP release series on the Heroku platform follows the PHP Group’s support policy, typically with active updates for two years after an initial x.y.0 version, followed by a year of security updates.

Once a PHP release series has reached end-of-life, it will no longer be supported by Heroku, but its latest release will remain available for builds to allow customers to upgrade their applications to a newer PHP version.

Available versions

The following table lists the runtime versions that are available for builds on each stack.

Runtime settings

All PHP runtimes use the respective release’s php.ini-production file as their base php.ini configuration.

Notwithstanding the above, the following INI directives are set to Heroku-specific values:

• date.timezone is set to UTC
• error_reporting is set to
  • E_ALL & ~E_STRICT for PHP versions before 8.1
  • E_ALL & ~E_STRICT & ~E_DEPRECATED for PHP 8.1 or later
• expose_php is set to Off
• session.sid_length is set to 32 (for PHP 7.1 and later)
• short_open_tag is set to On
• user_ini.cache_ttl is set to 86400
• variables_order is set to EGPCS

In addition, the PHP runtimes always have OPcache enabled for improved performance, with the following configuration changes optimized for the specific characteristics of Heroku’s dynos:

• opcache.enable_cli is set to 1
• opcache.validate_timestamps is set to 0

PHP CLI

The memory_limit PHP INI directive for the php CLI executable defaults to the full available dyno memory for PHP versions 7.2 or later. This means that e.g. worker dynos using a php command use this memory limit instead of the default PHP INI value of 128M.

Default runtime

Applications that do not use a composer.json, or where composer.lock contains no requirements for package php even in any dependent package, will pick the latest possible version of either PHP 7 or PHP 8 on the heroku-20 stack, and PHP 8 on all other stacks.

Selecting a runtime

You may select the runtime(s) to use via Composer Platform Packages in composer.json. Upon a push, Heroku will read the necessary information from composer.lock, if present, and fall back to composer.json otherwise.

For example, the following composer.json will instruct Heroku to use the latest version of PHP 8 greater or equal to 8.2.0, but not PHP 9:

{
  "require": {
    "php": "^8.2.0"
  }
}

Heroku will print the versions that were resolved and will be installed:

-----> Installing platform packages...
       - php (8.2.13)

Specifying an unknown or unsupported version will result in an error listing potential alternative versions.

PHP

Specify “php” as a dependency in the require section of your composer.json to use PHP as the runtime; for instance, for PHP 8.1 or later:

{
  "require": {
    "php": "^8.1.0"
  }
}

Next, ensure that your new requirements are “frozen” to composer.lock by running:

$ composer update

Finally, don’t forget to git add and git commit both files!

Upgrades

If you deploy an application that does not declare a runtime version dependency, the then-latest version of PHP will be used. Your application will be upgraded to more recent versions of PHP if available automatically upon the next deploy.

If your application declares runtime version dependencies, the most recent version matching the version constraint will be selected for installation.

Extensions

Available built-in extensions

The following table lists which of the built-in extensions that are bundled with PHP are available for each release series of PHP, and whether the extension in question is loaded by default, or whether it has to be explicitly enabled via composer.json.

Available third-party extensions

The following table lists which third-party extensions are available for each release series of PHP. As these are distributed independently of the PHP runtime, their versions are also listed. They are never loaded by default and thus have to be explicitly enabled via composer.json.

Using optional extensions

You may declare any optional extensions you want to use via composer.json using Composer Platform Packages; simply prefix any of the identifiers in the list of extensions above with “ext-” in the package name.

For example, to enable the optional bundled extensions bcmath and GMP, as well as the third-party Memcached, and a particular version of the third-party MongoDB:

{
    "require": {
        "ext-bcmath": "*",
        "ext-gmp": "*",
        "ext-memcached": "*",
        "ext-mongodb": "^1.19.0"
    }
}

Next, ensure that your new requirements are “frozen” to composer.lock by running:

$ composer update

Finally, don’t forget to git add and git commit both files!

$ composer update --ignore-platform-reqs

Upon the next push, Heroku will install and enable the corresponding PHP extensions:

-----> Installing platform packages...
       - php (8.2.13)
       - ext-bcmath (bundled with php)
       - ext-mcrypt (bundled with php)
       - ext-mongodb (1.17.0)
       - ext-memcached (3.2.0)
       - apache (2.4.58)
       - nginx (1.24.0)

Treatment of extensions “provided” by userland packages

Certain Composer packages such as the various Symfony Polyfills declare a native PHP extension as provided in their package metadata (and implement the functionality of that extension, partially or completely, purely using PHP code), which causes Composer to consider them a possible replacement of the real, native PHP extension during the resolution of dependencies.

During a build, these “polyfill” declarations are honored by Heroku when installing platform packages, using the exact same rules that Composer applies to the installation of packages.

This means that a requirement of composer.json (or any dependency) for e.g. ext-mbstring would not lead to the installation of the native ext-mbstring extension if the symfony/polyfill-mbstring package is also present in composer.lock, as symfony/polyfill-mbstring declares ext-mbstring as provided:

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)

For maximum performance and compatibility, after the initial resolving of platform package dependencies has finished in this manner, Heroku’s PHP Support will then attempt to install native versions of all extensions that userland packages have declared as provided:

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)
       NOTICE: detected userland polyfill packages for PHP extensions
       NOTICE: now attempting to install native extension packages
       Installing extensions provided by symfony/polyfill-mbstring:
       - ext-mbstring (bundled with php)

These installation attempts may not always be successful, as the extension in question may not be available on Heroku, or for the selected PHP version:

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)
       NOTICE: detected userland polyfill packages for PHP extensions
       NOTICE: now attempting to install native extension packages
       Installing extensions provided by phpseclib/mcrypt_compat:
       NOTICE: no suitable native version of ext-mcrypt available

In particular, no changes will be made to platform packages that have already been resolved: if a native variant is not available for the installed PHP version, no downgrade to a PHP version for which such an extension is available will be performed, even if that lower PHP version would be permitted by all other dependencies.

This behavior ensures that userland polyfill packages can correctly serve their purpose where necessary, such as when acting as a replacement for an extension that is no longer bundled with PHP (like e.g. phpseclib/mcrypt_compat does for ext-mcrypt in the example above), while simultaneously ensuring that the native PHP extension in question is installed whenever possible for maximum performance and compatibility.

Customizing settings

PHP

Any .user.ini file that is placed into a project according to the instructions in the PHP manual will be loaded after the main php.ini. You can use these to set any directive permitted in PHP_INI_ALL, PHP_INI_USER and PHP_INI_PERDIR contexts.

For additional details on this and other ways of customizing settings for the PHP runtime, please refer to the corresponding Dev Center article.

Build behavior

Installation of dependencies

The following command is run during a deploy to resolve dependencies unless composer.json is empty and no composer.lock is present:

$ composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

The installed version of Composer will be printed for your reference before installation begins. Builds are run using the a Composer version (1.x, 2.2.x LTS, or 2.3+) that is compatible with an application’s composer.lock. The respective version of Composer is available on $PATH at app runtime under the command name composer.

An application’s Composer cache directory is persisted between builds to speed up package installation on subsequent deploys.

Available Composer versions

The following Composer versions are currently available:

Custom compile step

For applications that wish to execute an additional compilation step during a build that shouldn’t be part of a standard post-install-cmd Composer script, for example an asset compilation or cache pre-warming procedure, a compile custom command, if present in composer.json, will be executed using the following command:

$ composer compile --no-dev --no-interaction

Any such custom script command defined in composer.json can either be a single string, or an array of multiple commands to execute; example:

{
  "scripts": {
    "compile": [
      "@php app/console assetic:dump --env=prod --no-debug",
      "MyVendor\\MyClass::postDeployComposerCallback"
    ]
  }
}

Private repositories

To use private repositories such as Private Packagist, or packages from a source that requires authentication (such as from a private GitHub repository), Composer must be provided with authentication details (typically a token generated by the provider or service).

On a development machine, these are typically stored by Composer in auth.json, but on Heroku, such secrets are stored as environment variables. The COMPOSER_AUTH environment variable is automatically read by Composer; its JSON structure is identical to auth.json.

The following entries are allowed as top-level keys in the JSON document:

• http-basic
• github-oauth
• gitlab-oauth
• gitlab-token
• bitbucket-oauth

Each entry then contains a hash of domains as keys and authentication details as values; the authentication detail structure is specific to each of the sources above and described in the documentation.

For example, to store authentication details for a Private Packagist, account, you’d set the COMPOSER_AUTH variable using heroku config:set with http-basic details (replacing “YOURTOKEN” with the actual token Private Packagist generated, of course):

$ heroku config:set COMPOSER_AUTH='{"http-basic":{"repo.packagist.com":{"username":"token","password":"YOURTOKEN"}}}'

To give another example, when using code from private GitHub repositories as Composer dependencies, a personal OAuth token can be set for authentication. After creating a new Token, you can set it on Heroku (replacing “YOURTOKEN” with the actual token GitHub generated, of course):

$ heroku config:set COMPOSER_AUTH='{"github-oauth":{"github.com":"YOURTOKEN"}}'

Several sets of authentication details can of course also be combined into a single document; for example, to use both private GitHub and private BitBucket repositories:

$ heroku config:set COMPOSER_AUTH='{
    "github-oauth": {"github.com": "YOURTOKEN"},
    "bitbucket-oauth": {"bitbucket.org": {
        "consumer-key": "YOURKEY", "consumer-secret": "YOURSECRET"}
    }
}'

Composer configuration

For convenience, the following settings for Composer are automatically set using environment variables:

• $COMPOSER_MEMORY_LIMIT defaults to the available dyno memory;
• $COMPOSER_MIRROR_PATH_REPOS defaults to 1;
• $COMPOSER_NO_INTERACTION defaults to 1.

Runtime behavior

The $PATH environment variable contains all necessary paths for an application to function at runtime. The Composer bin-dir is appended to $PATH for convenience.

PHP-FPM configuration

PHP-FPM is set up to automatically spawn a suitable number of worker processes depending on dyno size and the configured PHP memory_limit. Please refer to the Optimizing PHP Application Concurrency article for more details.

Timeouts

When a request reaches the Heroku router’s request timeout, a PHP-FPM process would continue to run, potentially as long as it takes for e.g. an external timeout to occur. This would tie up that PHP-FPM process, which could then no longer respond to other incoming requests.

For applications using PHP 7.4 or later, by default, PHP-FPM will therefor

• log a backtrace of requests that take longer than three seconds (request_slowlog_timeout directive), and
• terminate requests that have exceeded an execution time of 30 seconds (request_terminate_timeout directive) and therefor likely timed out.

You may adjust the settings for PHP-FPM to change these (or other) configuration settings.

Composer configuration

For convenience, the following settings for Composer are automatically set using environment variables:

• $COMPOSER_MEMORY_LIMIT defaults to the available dyno memory;
• $COMPOSER_MIRROR_PATH_REPOS defaults to 1;
• $COMPOSER_NO_INTERACTION defaults to 1;
• $COMPOSER_PROCESS_TIMEOUT defaults to 0.

Web servers

Heroku supports Apache HTTPD 2.4 and Nginx as dedicated Web servers. For testing purposes, users may of course also use PHP’s built-in Web server, although this is not recommended.

In the absence of a Procfile entry for the “web” dyno type, the Apache Web server will be used together with the PHP runtime.

The following web server versions are supported, and will automatically be installed during a build:

Apache

Apache interfaces with PHP-FPM via FastCGI using mod_proxy_fcgi.

To start Apache together with PHP-FPM and all the correct settings, use the heroku-php-apache2 script:

web: heroku-php-apache2

By default, the root folder of your project will be used as the document root. To use a sub-directory, you may pass the name of a sub-folder as the argument to the boot script, e.g. “public_html”:

web: heroku-php-apache2 public_html

You can use regular .htaccess files to customize Apache’s behavior, e.g. for URL rewriting. For additional details on this and other options to customize settings for Apache, please refer to the corresponding Dev Center article.

Nginx

Nginx interfaces with PHP-FPM via FastCGI.

To start Nginx together with PHP-FPM and all the correct settings, use the heroku-php-nginx script:

web: heroku-php-nginx

By default, the root folder of your project will be used as the document root. To use a sub-directory, you may pass the name of a sub-folder as the argument to the boot script, e.g. “public_html”:

web: heroku-php-nginx public_html

For additional details on different ways of customizing settings for Nginx, please refer to the corresponding Dev Center article.

PHP Built-in Web server

For testing purposes, you may start PHP’s built-in Web server by using php -S 0.0.0.0:$PORT as the entry for “web” in your Procfile:

web: php -S 0.0.0.0:$PORT

You may also pass an alternative document root, or use a so called router script to process requests. For details, please refer to the PHP project’s documentation for the built-in Web server.