docs community resources blog github
Edit

How to Build PHP Apps with Paketo Buildpacks

This documentation explains how to use the Paketo PHP Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo PHP Buildpack Reference documentation.

Build a Sample App

To build a sample app locally with this CNB using the pack CLI, run

git clone https://github.com/paketo-buildpacks/samples
cd samples/php/builtin-server
pack build my-app --buildpack paketo-buildpacks/php \
  --builder paketobuildpacks/builder-jammy-full
copy to clipboard
Copied!

See samples for how to run the app.

NOTE: The Paketo Full builder is required because PHP relies on operating system libraries only present in the Full builder.

Configure PHP

Install a Specific PHP Version

The PHP Dist CNB allows you to specify a version of PHP to use during deployment. This version can be specified in a number of ways, including through the BP_PHP_VERSION environment variable, composer.lock, or composer.json file. When specifying a version of PHP, you must choose a version that is available within the buildpack. The supported versions can be found on the Paketo PHP Dist releases page.

The buildpack prioritizes the versions specified in each possible configuration location with the following precedence, from highest to lowest: BP_PHP_VERSION, composer.json, composer.lock.

Set the version via BP_PHP_VERSION

To configure the buildpack to use a specific PHP version when deploying your app, set the following environment variable at build time, either directly (ex. pack build my-app --env BP_PHP_VERSION=8.0.0) or through a project.toml file:

BP_PHP_VERSION="8.0.0"
copy to clipboard
Copied!

Set the version via a composer.json file

If your apps use composer, you can specify the PHP version your apps use during deployment by configuring the require field in the composer.json file. To configure the buildpack to use PHP v8.0 or greater when deploying your app, include the values below in your composer.json file:

{
  "require": {
    "php": ">=8.0"
  }
}
copy to clipboard
Copied!

If your app has a composer.lock file, the buildpack will use the PHP version defined there.

Unsupported: Using buildpack.yml

Specifying the PHP version through buildpack.yml has been removed as of PHP language family buildpack v1.0.0. To migrate from using buildpack.yml please set the $BP_PHP_VERSION environment variable.

Configure the PHP library directory

To add directories to the include_path set in the default php.ini, buildpack users can set the BP_PHP_LIB_DIR environment variable at build time.

  pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_LIB_DIR=some-lib-directory
copy to clipboard
Copied!

Configure PHP with a custom .ini file

If you’d like to configure custom .ini files in addition to the default php.ini provided by the PHP Dist buildpack, you can provide your own configuration file in the application source directory under a directory named .php.ini.d/. The path to the configuration you add will be appended onto the PHP_INI_SCAN_DIR during the build process, for use by PHP at runtime. Check out the reference docs about the PHP_INI_SCAN_DIR for more information about defaults.

Use Extensions

There are two ways to enable extensions when using the Paketo PHP Buildpack. The only extensions available for usage at this time are the ones that come with the distribution of PHP.

Enable extensions through a custom .ini snippet

An .ini snippet is a valid PHP configuration file. The buildpacks will look for any user-provided snippets under <APP-ROOT>/.php.ini.d/*.ini, as mentioned in the Configure PHP with a custom .ini file section.

An example snippet could look like:

extension=bz2.so
extension=curl.so
copy to clipboard
Copied!

Enable extensions through a composer.json

If you are using Composer as a package manager (see section below), you can specify extensions through the composer.json file.

An example of a composer.json file with extensions specified would look like:

{
    "require": {
        "php": ">=7.1",
        "ext-bz2": "*",
        "ext-curl": "*",
    },
}
copy to clipboard
Copied!

Configure Composer

The Composer and Composer Install buildpacks allow for user-set configuration options for Composer.

Set the Composer version

To define a version of Composer to use, set BP_COMPOSER_VERSION at build time. A supported version must be selected. The supported versions can be found on the Paketo Composer releases page. With the pack CLI, this looks like

pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_COMPOSER_VERSION="2.3.1"
copy to clipboard
Copied!

Set install options

To define a command line option for composer install to run, set the BP_COMPOSER_INSTALL_OPTIONS environment variable at build time to a space-separated list of flags.

pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_COMPOSER_INSTALL_OPTIONS="--no-dev --prefer-install=auto"
copy to clipboard
Copied!

To define global composer install configurations, set the BP_COMPOSER_INSTALL_GLOBAL environment variable at build time to a space-separated list of global installation options.

pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_COMPOSER_INSTALL_GLOBAL="friendsofphp/php-cs-fixer squizlabs/php_codesniffer=*"
copy to clipboard
Copied!

Set a custom Composer vendor directory

To define a custom vendoring location for Composer packages, users can set the COMPOSER_VENDOR_DIR environment variable at build time. It is a Composer-native environment variable setting. It must be set as a relative path under the application source directory root.

pack build my-app --buildpack paketo-buildpacks/php \
  --env COMPOSER_VENDOR_DIR="vendor"
copy to clipboard
Copied!

Set the composer.json path

To define a custom composer.json path, users can set the Composer-native environment variable COMPOSER at build time. The path must be relative to the project root.

pack build my-app --buildpack paketo-buildpacks/php \
  --env COMPOSER="some-other-composer.json"
copy to clipboard
Copied!

Set Composer authentication

To set up authentication for Composer, the Composer-native environment variable COMPOSER_AUTH can be set as a JSON-formatted object containing objects defined in the Composer docs.

pack build my-app --buildpack paketo-buildpacks/php \
  --env COMPOSER_AUTH='{"http-basic": <some-creds>}'
copy to clipboard
Copied!

Select a web server

The PHP buildpack supports the use of 3 different web servers:

  • PHP Built-in Web Server (default)
  • Apache HTTPD Web Server
  • NGINX Web Server

You can configure which web server to use by setting the BP_PHP_SERVER environment variable at build time. The setting options are php-server, httpd, nginx, with the default value of php-server if unset. The PHP Built-in Server buildpack will only pass detection if there is a *.php file in the web directory of the application.

  pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_SERVER="php-server"
copy to clipboard
Copied!

Unsupported: Using buildpack.yml

Selecting a web server through buildpack.yml configuration has been removed as of PHP language family buildpack v1.0.0. To migrate from using buildpack.yml please set the environment variable equivalent instead.

Set server configuration

If you’re using httpd or nginx, a suitable httpd.conf or nginx.conf will be generated for you by the buildpack and made available in a layer. Check out the PHP Reference documentation for an enumeration of the defaults set for httpd and nginx.

Additional configuration can also be provided via environment variables.

Provide your own web server configuration file

If either httpd or nginx are the selected web server via the BP_PHP_SERVER environment variable, users can provide their own configurations in the form of a server-specific configuration file.

Provide httpd specific configuration

To provide your own HTTPD configuration, place *.conf files in your application source directory under <app-directory>/.httpd.conf.d/*.conf. This is helpful in the event that you want to set custom settings that are not configurable via environment variables in the PHP HTTPD buildpack.

Provide nginx specific configuration

To provide your own NGINX configuration, place configuration files in your application source directory under <app-directory>/.nginx.conf.d/. Server-specific configuration should be inside a file whose name ends with -server.conf (e.g. prod-server.conf), and HTTP configuration should be inside a file whose name ends with -http.conf (e.g. prod-http.conf). This is helpful in the event that you want to set custom settings that are not configurable via environment variables in the PHP NGINX buildpack. Check out NGINX documentation for what settings can be applied to server and HTTP blocks.

Configure FPM settings

The PHP buildpack includes support for the PHP FastCGI Process Manager (FPM) when used in conjunction with a web server. In this case, the PHP FPM buildpack will generate FPM configuration for you to work with the web server of choice. The buildpack will also consider configuration from user provided sources (see Override Default FPM Configuration).

Check out the PHP Reference documentation for an enumeration of the defaults set for FPM.

Override Default FPM Configuration

Users can provide FPM configuration by providing a configuration file in the application source directory under <app-directory>/.php.fpm.d/*.conf.

User-provided configuration will be considered the highest precedence source of configuration, and should be provided in an .ini compliant format in order to be considered by PHP FPM.

Configure the web directory

The top-level directory where a web server finds files to serve is the web directory. In the PHP buildpack, when the web server is HTTPD or NGINX, the web directory defaults to htdocs. When the web server is the PHP built-in server, the web directory defaults to /workspace.

In all cases, the default web directory can be overridden by setting the BP_PHP_WEB_DIR environment variable at build time. The value provided should be a path relative to the application root.

Note: The PHP built-in server will only pass detection if a *.php file is found inside of the web directory.

  pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_WEB_DIR="some-web-dir"
copy to clipboard
Copied!

Enable/disable HTTPS

The HTTPS enable feature is an opt-in environment variable configuration available for PHP apps that use NGINX. It defaults to the disabled state, and can be enabled by setting the BP_PHP_NGINX_ENABLE_HTTPS environment variable to true at build time. When this feature is enabled, the NGINX server is configured to accept connections in SSL mode, thus enabling it to handle HTTPS requests.

For PHP apps that use HTTPD, you can provide the configuration to enable HTTPS in a .httpd.conf.d directory at the root of the app. NGINX workloads have a dedicated environment variable because it’s not possible to override this configuration from a user-provided config file and needs to be set in the configuration generated by the buildpack.

  pack build my-php-nginx-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_NGINX_ENABLE_HTTPS=true
copy to clipboard
Copied!

Enable/disable HTTPS Redirect

The HTTPS redirect feature is enabled by default in the nginx and httpd cases. It can be disabled by setting the BP_PHP_ENABLE_HTTPS_REDIRECT environment variable to false at build time. When this feature is enabled, the server will redirect HTTP requests to HTTPS. Check out server-provided documentation for details on what this entails for each case.

  pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_ENABLE_HTTPS_REDIRECT=false
copy to clipboard
Copied!

Configure server admin for HTTPD

The server admin in the httpd case can be overridden from the default of admin@localhost via the BP_PHP_SERVER_ADMIN environment variable at build time.

  pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_PHP_SERVER_ADMIN=some-admin@localhost
copy to clipboard
Copied!

Override the start process

By default, the buildpacks will determine the right start command to run depending on the server that is being used. A user can override the start command by using the Paketo Procfile buildpack. Check out the Procfiles section of our configuration docs for details on how to use the buildpack.

Enable a session handler via service bindings

The PHP Buildpack supports using session handlers for Memcached and Redis instances via the PHP Memcached Session Handler Buildpack and the [PHP Redis Session Handler Buildpack][bp/php-redis-session-handler]. Check out the PHP session handler documentation for more information on what a PHP session handler is.

In order to configure a session handler for either Redis or Memcached the user must provide a service binding.

Enable the session handler for Redis

To configure a Redis instance session handler, the provided service binding should contain the following:

Binding File Value Required Description
type php-redis-session yes Binding type
host or hostname Default: 127.0.0.1 no Redis instance IP address
port Default: 6379 no Redis instance port
password Omitted if unset no Redis instance password

When performing a build with the pack CLI, passing the service binding will look like the following:

  pack build my-app --buildpack paketo-buildpacks/php \
  --env SERVICE_BINDING_ROOT=/bindings \
  --volume <absolute-path-to-binding>:/bindings/php-redis-session
copy to clipboard
Copied!

Enable the session handler for Memcached

To configure a Memcached instance session handler, the provided service binding should contain the following:

Binding File Value Required Description
type php-memcached-session yes Binding type
servers Default: 127.0.0.1 no Memcached instance IP address
username Omitted if unset no Memcached instance username
password Omitted if unset no Memcached instance password

When performing a build with the pack CLI, passing the service binding will look like the following:

  pack build my-app --buildpack paketo-buildpacks/php \
  --env SERVICE_BINDING_ROOT=/bindings \
  --volume <absolute-path-to-binding>:/bindings/php-memcached-session
copy to clipboard
Copied!

Install a custom CA certificate

Users of the PHP buildpack can provide their own CA certificates and have them included in the container root truststore at build time and runtime by following the instructions outlined in the CA Certificates section of our configuration docs.

Set environment variables for app launch time

PHP buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.

Add custom labels to the app image

PHP buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.

Enable DEBUG logging

Users of the PHP buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL environment variable to DEBUG at build time. Additional debug logs will appear in build logs if the relevant buildpacks have debug log lines.

pack build my-app --buildpack paketo-buildpacks/php \
  --env BP_LOG_LEVEL=DEBUG
copy to clipboard
Copied!

Access the software bill of materials

The PHP buildpack includes support for the software bill of materials (SBOM). Check out the SBOM how-to documentation for details on how to access the SBOM supplied by the buildpacks.

Edit

Last modified: December 6, 2024