Specifying a PHP Runtime
Last updated March 17, 2025
Table of Contents
You can specify which runtime(s) to use in your composer.json file. Upon a push, Heroku reads the necessary information from composer.lock, if present, and falls back to composer.json otherwise.
Specifying a Runtime
For example, here composer.json instructs 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"
}
}
Never specify an exact version like “8.2.13” for PHP, or any other package.
Instead, use the “^” or “~” next significant release operators to ensure that you get appropriate updates upon push as they become available.
For example, specifying “~8.2.0” provides the latest 8.2.x release. This specification is fully compatible with other releases from the 8.2 series, but may contain security or performance updates. It is not compatible with PHP 8.3 or later.
To get the latest PHP 8.2 or later (including PHP 8.3, 8.4, and so on) but not PHP 9, specify “^8.2.0”.
Heroku prints the versions that are resolved and installs:
-----> Installing platform packages...
- php (8.2.13)
Specifying an unknown or unsupported version results 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 example, for PHP 8.1 or later:
{
"require": {
"php": "^8.1.0"
}
}
It’s recommended you always prefix the minimum version you’d like to use with the ^ selector. This ensures that you receive updated versions as they become available. In the example above, you get PHP 8.1.0 or later, including newer versions in the 8.x series. You won’t get PHP 9 (when it’s released) until you change your specification.
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!