Page last updated:

Composer is activated when you supply a composer.json and composer.lock file.

You can require dependencies for packages and extensions. Extensions must be prefixed with the standard ext-. If you reference an extension that is available to the buildpack, it will automatically be installed and enabled. For a list of supported extensions, see the Releases page of php-cnb in GitHub.

The buildpack uses the version of PHP specified in your composer.json and composer.lock file. Composer settings override the version set in the options.json or buildpack.yml file.


The buildpack runs with a set of default values for Composer. You can adjust these values by adding a buildpack.yml file to your application and setting any of the following values in it.

Variable Explanation
composer.version The version of Composer to use. It defaults to the latest bundled with the buildpack.
composer.install_options A list of options that should be passed to composer install. This defaults to --no-interaction --no-dev --no-progress. The --no-interaction and --no-progress options must be used due to the way the buildpack calls Composer.
composer.vendor_directory Allows you to override the default vendor directory used by the buildpack. Must be a relative path. This is passed through to Composer instructing it where to create the vendor directory and can also be use to change the name of the vendor directory. Defaults to vendor.

Vendor dependencies will be located under this relative path within the Composer layer. In addition, a symlink to this directory will be created at the same relative path under the application root.
composer.json_path By default, composer.json and composer.lock may exist under the applictiaon root or under the application’s public web directory. You may set this option to search for these files in a different sub-directory of the application root or public web directory. The pair of files must both exist in the same location.

Ex: if composer.json_path is set to config, then app_root/config/composer.json and app_root/webdir/composer.json will be checked.
composer.install_global A list of package names to be installed globally. This calls composer global require for each package listed here.

To make it easier to read, dot notation is used in the table. However, this should be expanded into YAML format. Here is an example buildpack.yml:

  version: 7.2.14
  webserver: nginx
  version: 1.17.5
  install_options: '--no-dev --optimize-autoloader'
  vendor_directory: 'dependencies'

GitHub API Request Limits

Composer uses GitHub’s API to retrieve zip files for installation into the application folder. If you do not vendor dependencies before pushing an app, Composer will fetch dependencies during staging using the GitHub API.

GitHub’s API is request-limited. If you reach your daily allowance of API requests (typically 60), GitHub’s API returns a 403 error and staging fails.

There are two ways to avoid the request limit:

  1. Vendor dependencies before pushing your application.
  2. Supply a GitHub OAuth API token.

Vendor Dependencies

To vendor dependencies, you must run composer install before you push your application.

By default, dependencies need to exist in a vendor directory under the root of your application. Optionally, you can set composer.vendor_directory in buildpack.yml to a different relative path under your application root where your dependencies are stored.

Supply a GitHub Token

Composer can use GitHub API OAuth tokens, which increase your request limit, typically to 5000 per day.

During staging, the buildpack looks for this token in the environment variable COMPOSER_GITHUB_OAUTH_TOKEN. If you supply a valid token, Composer uses it. This mechanism does not work if the token is invalid.

To supply the token, you can use either of the following methods:

  2. Add the token to the env block of your application manifest.

Buildpack Staging Environment

Composer runs in the buildpack staging environment. Variables set with cf set-env or with a manifest.yml ‘env’ block are visible to Composer.

For example:

$ cf push a_symfony_app --no-start
$ cf set-env a_symfony_app SYMFONY_ENV "prod"
$ cf start a_symfony_app

In this example, a_symfony_app is supplied with an environment variable, SYMFONY_ENV, which is visible to Composer and any scripts started by Composer.

Non-Configurable Environment Variables

User-assigned environment variables are applied to staging and runtime. The following environment variables cannot be overridden by users:

  • COMPOSER_HOME : Set to $COMPOSER_LAYER/.composer
  • PHPRC : Set to $COMPOSER_LAYER/composer-php.ini
  • PHP_INI_SCAN_DIR : Set to $APP_ROOT/.php.ini.d
Create a pull request or raise an issue on the source for this page in GitHub