PHP Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo PHP Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo PHP Buildpack How To documentation.

Supported Dependencies

The Paketo PHP Buildpack supports several versions of PHP and Composer. For more details on the specific versions supported in a given buildpack version, see the release notes.

Behavior

The Paketo PHP Buildpack is a composite buildpack designed to build applications written in PHP.

Package Management

With the PHP CNB, the only option for package management is Composer.

The Composer buildpack will install composer as the package manager, and if a PHP application contains a composer.json (and preferably a composer.lock file) packages are installed by running composer install by the Composer Install buildpack. Packages installed will be available in a vendor directory in the application source directory, and will be cached for rebuilds.

Running With Webservers

The buildpacks within the PHP CNB will configure basic configuration for working with FPM, HTTPD, NGINX, or the built-in PHP webserver. Web server choice is set by the user via environment variable (see PHP How To documentation), and user-provided configurations will be considered as outlined below.

Software Bill of Materials

The PHP buildpack supports the full software bill of materials (SBOM) in Syft, CycloneDX, SPDX, and Paketo-specific formats.

Apps built with the buildpack that use Composer as a package manager contain SBOM entries that provide a full picture of the packages installed in the final app image. There are also entries for the installed versions of PHP and Composer. Check out the Access the Software Bill of Materials guide for more information about how to retrieve the SBOM for your app image.

Buildpack Configurations

The buildpacks in the PHP language family set default configurations, as well as include configurations from user-provided sources. The sections below outline the various configurations the buildpacks provide during the build process, and the various locations that will also be considered as configuration sources.

PHP Distribution Buildpack Configuration

This section lists the various configuration sources for PHP .ini files that are made available to PHP at run-time.

1. The default PHP ini file found from the PHP Distribution itself, with no modifications. It can be found on the container inside the PHP Distribution Buildpack layer under /etc/php.ini.
2. Buildpack-specific configuration which can be found inside the PHP Distribution Buildpack layer under /etc/buildpack.ini. This includes configurations specific to the buildpack’s install process and app image file system, such as the path to PHP extensions (extension_dir), the include path to the PHP library directory.
3. User-provided configurations from the <APP-ROOT>/.php.ini.d directory.

Check out the PHP_INI_SCAN_DIR documentation section for more information.

PHP FPM Buildpack Configuration

Configuration for PHP FPM comes from a few sources, listed here in order of precedence from highest to lowest:

1. User-provided configurations located in <APP-ROOT>/.php.fpm.d/*.conf.
2. Configuration set by other buildpacks (such as the PHP NGINX Buildpack FPM configuration), which is stored in /workspace/.php.fpm.bp/*.conf files.
3. Buildpack-specific configuration, which includes configurations specific to the buildpack’s role in the build process. This includes settings such as the default listen directive, and other features to make FPM work well with web servers.
4. The default PHP FPM configuration that is distributed alongside the PHP Distribution itself. This is stored at $PHPRC/php-fpm.d/www.conf.default in the container.

PHP NGINX Buildpack Configuration

The PHP NGINX Buildpack sets up two flavours of configuration itself, and allows for a third flavour from users. They are listed here in order of highest precedence, to lowest.

1. User-provided configuration files located in <APP-ROOT>/.nginx.conf.d/*-http.conf and <APP-ROOT>/.nginx.conf.d/*-server.conf The former can be used to include user-specific config in the http block, while the latter is used to include user-specific config in the http.server block in the nginx.conf generated by the buildpack.
2. Basic NGINX configuration is the nginx.conf file for running with PHP apps. See PHP How To documentation for settings that can be configured via environment variables.
3. NGINX-specific FPM settings (see FPM section above) is added to work with FPM.

PHP HTTPD Buildpack Configuration

1. Basic HTTPD configuration is the httpd.conf file for running with PHP apps. See PHP How To documentation for settings that can be configured via environment variables.
2. User-provided configuration files located in <APP-ROOT>/.httpd.conf.d/*.conf.

Composer Install Buildpack Configuration

The Composer Install Buildpack sets up configuration to be used for running composer commands. They are listed here in no specific order.

1. A Composer PHP .ini file is created for usage during the buildpack build process only. It will tell Composer where to find extensions when running composer-install.
2. Platform requirement .ini file available on the final image under /workspace/.php.ini.d/composer-extensions.ini which will be appended onto the PHP_INI_SCAN_DIR. It will include any composer.json specified extensions that come from running the Composer check-platform-reqs command.

Buildpack-Set Environment Variables

The buildpacks within the Paketo PHP language family set a number of environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.

PATH

• Set by: php-dist and composer-install (build phase only)
• Phases: build and launch
• Value: path to the PHP executable

PHP_INI_SCAN_DIR

• Set by: php-dist, php-redis-session-handler, and php-memcached-session-handler buildpacks
• Phases: build and launch
• Value: directories where PHP ini configuration can be found.

PHPRC

• Set by: php-dist and composer-install (build phase only)
• Phases: build and launch
• Value: path to the top-level official PHP Distribution-provided php.ini

PHP_API

• Set by: php-dist buildpack
• Phases: build and launch
• Value: internal api version (YYYYMMDD)

PHP_EXTENSION_DIR

• Set by: php-dist buildpack
• Phases: build and launch
• Value: location of directory with dynamic libraries for extensions

PHP_HOME

• Set by: php-dist buildpack
• Phases: build and launch
• Value: location of PHP installation

MIBDIRS

• Set by: php-dist buildpack
• Phases: build and launch
• Value: See PHP documentation

APP_ROOT

• Set by: httpd buildpack
• Phases: launch
• Value: path of app source

SERVER_ROOT

• Set by: httpd buildpack
• Phases: launch
• Value: path of the httpd installation

COMPOSER

• Set by: composer-install buildpack
• Phases: build
• Value: path to the composer.json file

COMPOSER_HOME

• Set by: composer-install buildpack
• Phases: build
• Value: Composer home directory

COMPOSER_VENDOR_DIRECTORY

• Set by: composer-install buildpack
• Phases: build
• Value: Composer packages vendor directory

COMPOSER_NO_INTERACTION

• Set by: composer-install buildpack
• Phases: build
• Value: Pass the --no-interaction flag to Composer commands

PHP_FPM_PATH

• Set by: php-fpm buildpack
• Phases: build and launch
• Value: path to the FPM configuration for usage in FPM start command

PHP_HTTPD_PATH

• Set by: php-httpd buildpack
• Phases: build and launch
• Value: path to the HTTPD configuration for usage in server start command

PHP_NGINX_PATH

• Set by: php-nginx buildpack
• Phases: build and launch
• Value: path to the NGINX configuration for usage in NGINX start command

Components