docs community blog github

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
cd samples/php/webserver
pack build my-app --buildpack \
  --builder paketobuildpacks/builder:full
copy to clipboard

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.

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 buildpack.yml or composer.json files. When specifying a version of PHP, you must choose a version that is available within the buildpack.

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

Using buildpack.yml

To configure the buildpack to use PHP version when deploying your app, include the values like below in your buildpack.yml file. Any valid semver constraints are acceptable.

  version: 7.2.*
copy to clipboard

Using composer.json

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 v7.1 or greater when deploying your app, include the values below in your composer.json file:

  "require": {
    "php": ">=7.1"
copy to clipboard

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

Configure Composer

The following options are configurable in the app’s buildpack.yml

  # this allows you to specify a version constaint for composer
  # any valid semver constaints (e.g. 1.* and 1.10.*) are also acceptable
  version: 1.10.x

  # a list of command line install options for composer
  # default: ["--no-dev"]
  install_options: ["--no-dev"]

  # default: vendor
  vendor_directory: vendor

  # directory where composer.json can be found
  # default is app root
  json_path: composer

  # if included, will run `composer global` with specified arguments
  install_global: ["list", "of", "install", "options"]
copy to clipboard

Select a Web Server

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

  • PHP built-in Web Server
  • Apache HTTP Web Server
  • Nginx Web Server

You can configure the webserver using buildpack.yml as follows:

  # options are: php-server, httpd, nginx. default: php-server
  webserver: php-server
copy to clipboard

If you’re using httpd or nginx, a suitable httpd.conf or nginx.conf will be generated for you by the buildpack.

You can also provide additional configurations like follows:

# buildpack.yml
  # directory where web app code is stored
  # default: htdocs
  webdirectory: htdocs

  # directory where library code is stored
  # default: lib
  libdirectory: lib

  # cli script to use
  # no default

  # default: admin@localhost
  serveradmin: admin@localhost
copy to clipboard

Vendor composer packages

If your php app that uses composer has a valid vendor directory, then the buildpack will not download those packages. It will instead use the packages location in the vendor directory.

Configure custom .ini files

If you like to configure custom .ini files in addition to the php.ini provided by the buildpack, you can create a directory named .php.ini.d at the root of your app and put your custom ini files there. See PHP_INI_SCAN_DIR in the Variables section below.

Install a Custom CA Certificate

PHP buildpack users 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.

Override the Start Process Set by the Buildpack

PHP buildpack users can set custom start processes for their app image by following the instructions in the Procfiles 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.


Last modified: December 3, 2021