PHP Buildpack Configuration

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.


The PHP buildpack stores all of its default configuration settings in the defaults directory.


The options.json file is the configuration file for the buildpack itself. It instructs the buildpack what to download, where to download it from, and how to install it. It allows you to configure package names and versions (i.e. PHP, HTTPD, or Nginx versions), the web server to use (HTTPD, Nginx, or None), and the PHP extensions that are enabled.

The buildpack overrides the default options.json file with any configuration it finds in the .bp-config/options.json file of your application.

Below is an explanation of the common options you might need to change.

Variable Explanation
WEB_SERVER Sets the web server to use. Must be one of httpd, nginx, or none. This value defaults to httpd.
HTTPD_VERSION Sets the version of Apache HTTPD to use. Currently the build pack supports the latest stable version. This value will default to the latest release that is supported by the build pack.
ADMIN_EMAIL The value used in HTTPD’s configuration for ServerAdmin
NGINX_VERSION Sets the version of Nginx to use. By default, the buildpack uses the latest stable version.
PHP_VERSION Sets the version of PHP to use.
Set to a minor instead of a patch version,
such as "{PHP_70_LATEST}". See options.json.
PHP_EXTENSIONS (DEPRECATED) A list of the extensions to enable. bz2, zlib, curl, and mcrypt are enabled by default.
PHP_MODULES A list of the modules to enable. No modules are explicitly enabled by default, but the buildpack automatically chooses either fpm or cli. You can explicitly enable any or all of the following: fpm, cli, cgi, and pear.
ZEND_EXTENSIONS A list of the Zend extensions to enable. Nothing is enabled by default.
APP_START_CMD When the WEB_SERVER option is set to none, this command is used to start your app. If WEB_SERVER and APP_START_CMD are not set, then the buildpack searches, in order, for app.php, main.php, run.php, or start.php. This option accepts arguments.
WEBDIR The root directory of the files served by the web server specified in WEB_SERVER. Defaults to htdocs. Other common settings are public, static, or html. The path is relative to the root of your application.
LIBDIR This path is added to PHP’s include_path. Defaults to lib. The path is relative to the root of your application.
HTTP_PROXY The buildpack downloads uncached dependencies using HTTP. If you are using a proxy for HTTP access, set its URL here.
HTTPS_PROXY The buildpack downloads uncached dependencies using HTTPS. If you are using a proxy for HTTPS access, set its URL here.
ADDITIONAL_PREPROCESS_CMDS A list of additional commands that run prior to the application starting. For example, you might use this command to run migration scripts or static caching tools before the application launches.

For details about supported versions, see the release notes for your buildpack version.

HTTPD, Nginx, and PHP configuration

The buildpack automatically configures HTTPD, Nginx, and PHP for your application. This section explains how to modify the configuration.

The .bp-config directory in your application can contain configuration overrides for these components. Name the directories httpd, nginx, and php. We recommend that you use php.ini.d or fpm.d.

NOTE: If you override the php.ini or php-fpm.conf files, many other forms of configuration will not work.

For example: .bp-config httpd nginx php

Each directory can contain configuration files that the component understands.

For example, to change HTTPD logging configuration:

$ ls -l .bp-config/httpd/extra/
total 8
-rw-r--r--  1 daniel  staff  396 Jan  3 08:31 httpd-logging.conf

In this example, the httpd-logging.conf file overrides the one provided by the buildpack. We recommend that you copy the default from the buildpack and modify it.

You can find the default configuration files in the PHP Buildpack /defaults/config directory.

You should be careful when modifying configurations, as doing so can cause your application to fail, or cause Cloud Foundry to fail to stage your application.

You can add your own configuration files. The components will not know about these, so you must ensure that they are included. For example, you can add an include directive to the httpd configuration to include your file:

ServerRoot "${HOME}/httpd"
Listen ${PORT}
ServerName ""
DocumentRoot "${HOME}/#{WEBDIR}"
Include conf/extra/httpd-modules.conf
Include conf/extra/httpd-directories.conf
Include conf/extra/httpd-mime.conf
Include conf/extra/httpd-logging.conf
Include conf/extra/httpd-mpm.conf
Include conf/extra/httpd-default.conf
Include conf/extra/httpd-remoteip.conf
Include conf/extra/httpd-php.conf
Include conf/extra/httpd-my-special-config.conf # This line includes your additional file.


The buildpack adds any .bp-config/php/php.ini.d/FILE-NAME.ini files it finds in the application to the PHP configuration. You can use this to change any value acceptable to php.ini. See for a list of directives.

For example, adding a file .bp-config/php/php.ini.d/something.ini to your app, with the following contents, overrides both the default charset and mimetype.


In order of highest precedence, php configuration values come from the following sources:

  • php scripts using ini_set() to manually override config files
  • user.ini files for local values
  • .bp-config/php/php.ini.d to override master value, but not local values from user.ini files


The buildpack adds any files it finds in the application under .bp-config/php/fpm.d that end with .conf (i.e my-config.conf) to the PHP-FPM configuration. You can use this to change any value acceptable to php-fpm.conf. See for a list of directives.

PHP FPM config snippets are included by the buildpack into the global section of the configuration file. If you need to apply configuration settings for a PHP FPM worker, that needs to be indicated in your configuration file as well.

For example:

; This option is specific to the `www` pool
catch_workers_output = yes

PHP Extensions

The buildpack adds any .bp-config/php/php.ini.d/FILE-NAME.ini files it finds in the application to the PHP configuration. You can use this to enable PHP or ZEND extensions. For example:

If an extension is already present and enabled in the compiled php, for example intl, you do not need to explicitly enable it to use that extension.


PHP has two kinds of extensions, PHP extensions and Zend extensions. These hook into the PHP executable in different ways. See for more information about the way extensions work internally in the engine.

Because they hook into the PHP executable in different ways, they are specified differently in ini files. Apps fail if a Zend extension is specified as a PHP extension, or a PHP extension is specified as a Zend extension.

If you see the following error, move the example extension from extension to zend_extension, then re-push your app:

php-fpm | [warn-ioncube] The example Loader is a Zend-Engine extension and not a module (pid 40)
php-fpm | [warn-ioncube] Please specify the Loader using 'zend_extension' in php.ini (pid 40)
php-fpm | NOTICE: PHP message: PHP Fatal error:  Unable to start example Loader module in Unknown on line 0

If you see the following error, move the example extension from zend_extension to extension, then re-push your app.

NOTICE: PHP message: PHP Warning: example MUST be loaded as a Zend extension in Unknown on line 0

PHP Modules

You can include the following modules by adding them to the PHP_MODULES list:

  • cli, installs php and phar
  • fpm, installs PHP-FPM
  • cgi, installs php-cgi
  • pear, installs Pear

By default, the buildpack installs the cli module when you push a standalone app, and installs the fpm module when you push a web app. You must specify cgi and pear if you want them installed.

Buildpack Extensions

The buildpack comes with extensions for its default behavior. These are the HTTPD, Nginx, PHP, and NewRelic extensions.

The buildpack is designed with an extension mechanism, allowing app developers to add behavior to the buildpack without modifying the buildpack code.

When you push an app, the buildpack runs any extensions found in the .extensions directory of your app.

The Developer Documentation explains how to write extensions.