Use the Tanzu PHP Buildpack

This topic tells you how to use the Tanzu PHP Buildpack.

The Tanzu PHP buildpack enables developers to build PHP-based applications.

The Tanzu PHP buildpack is only compatible with the Full ClusterBuilder in Tanzu Application Platform, or builders based on the Full Stack due to operating-system level libraries required by PHP.

Example Sample App Builds

This section demonstrates building the Paketo PHP HTTPD sample app on different platforms.

How to use in Tanzu Application Platform

Create a workload.yaml.

---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata:
  labels:
    app.kubernetes.io/part-of: php-sample
    apps.tanzu.vmware.com/has-tests: "true"
    apps.tanzu.vmware.com/workload-type: web
  name: php-sample
spec:
  build:
    env:
    - name: BP_PHP_SERVER
      value: "httpd"
  params:
  - name: ports
    value:
    - port: 80
      containerPort: 8000
      name: http
  source:
    git:
      ref:
        branch: main
      url: https://github.com/paketo-buildpacks/samples
    subPath: php/httpd

Where metadata.name is the application name the workload is a part of, and spec.source.git points to the remote source code. Note that the server choice of HTTPD is set as a build.env value through BP_PHP_SERVER.

Trigger an image build in the my-apps namespace by running:

tanzu apps workload apply --file workload.yaml --namespace my-apps

After the build completes, you can view the result by running:
```
tanzu apps workload get httpd-sample --namespace my-apps
```

How to use in Tanzu Build Service

The PHP buildpack is only available in the full descriptor of Tanzu Build Service. Use kp image create to create an image resource. For more information, see the Tanzu Build Service documentation.

How to use with `pack` CLI

You can use the pack CLI to build your application image.

From the app directory, build the image with pack:

pack build php-sample --env BP_PHP_SERVER=httpd --buildpack gcr.io/tanzu-buildpacks/php

After the build has succeeded, run the image:

docker run --interactive --tty --env PORT=8080 --publish 8080:8080 php-sample

View the running application by visiting http://localhost:8080 in a browser.

Specifying a PHP Version

The PHP Dist Cloud Native Buildpack (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 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 using `BP_PHP_VERSION`

To configure the buildpack to use a specific PHP version when deploying your app, set the BP_PHP_VERSION environment variable at build time.

Using `project.toml`

You can set the PHP version through a project.toml file:

BP_PHP_VERSION="8.0.0"

Passed to the platform

You can set the PHP version directly, by running:

pack build my-app --env BP_PHP_VERSION=8.0.0

Set the version using 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 later when deploying your app, include the values below in your composer.json file:

{
  "require": {
    "php": ">=8.0"
  }
}

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

(Unsupported) Set the version using the `buildpack.yml`

Specifying the PHP version through buildpack.yml has been removed as of PHP language family buildpack v3.0.0. To migrate from using buildpack.yml, 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 you can set the BP_PHP_LIB_DIR environment variable at build time.

[build]
  [[build.env]]
    name = "BP_PHP_LIB_DIR"
    value = "some-lib-directory"

Configure PHP with a custom `.ini` file

If you'd like to configure custom .ini files in addition to the default php.ini provided, 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.

For more information about the default PHP_INI_SCAN_DIR value, see Buildpack-Set Environment Variables later in this topic.

Use Extensions

There are two ways to enable extensions when using the Tanzu 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.

An example snippet could look like:

extension=bz2.so
extension=curl.so

Enable extensions through a `composer.json`

If you are using Composer as a package manager, 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": "*",
    },
}

Configure Composer

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

Set 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 in the Composer release notes. With the pack CLI, this looks like

[build]
  [[build.env]]
    name = "BP_COMPOSER_VERSION"
    value = "2.3.*" # any valid semver constraints are acceptable

Set Composer 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.

[build]
  [[build.env]]
    name = "BP_COMPOSER_INSTALL_OPTIONS"
    value = "--no-dev --prefer-install=auto"

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.

[build]
  [[build.env]]
    name = "BP_COMPOSER_INSTALL_GLOBAL"
    value = "friendsofphp/php-cs-fixer squizlabs/php_codesniffer=*"

Set a Custom Composer Vendor Directory

To define a custom vendoring location for Composer packages, you 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.

[build]
  [[build.env]]
    name="COMPOSER_VENDOR_DIR"
    value = "vendor"

Set the `composer.json` Path

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

[build]
  [[build.env]]
    name="COMPOSER"
    value = "some-other-composer-json"

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 documentation.

[build]
  [[build.env]]
    name="COMPOSER_AUTH"
    value = '{"http-basic": <some-creds>}'

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.

[build]
  [[build.env]]
    name="BP_PHP_SERVER"
    value = "php-server"

(Unsupported) Select a web server using the `buildpack.yml`

Selecting a web server through buildpack.yml configuration has been removed as of PHP language family buildpack v3.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. For an enumeration of the defaults set for httpd and nginx, see the Paketo PHP Reference documentation.

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 through the BP_PHP_SERVER environment variable, you can provide your 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. To find out which settings you can apply to server and HTTP blocks, see the NGINX documentation.

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 section below).

For an enumeration of the defaults set for FPM, see the PHP Reference documentation.

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 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 only passes detection if a *.php file is found inside of the web directory.

[build]
  [[build.env]]
    name = BP_PHP_WEB_DIR
    value = "some-web-dir"

Activate/Deactivate HTTPS Redirect

The HTTPS redirect feature is enabled by default for nginx and httpd. You can deactivate it by setting the BP_PHP_ENABLE_HTTPS_REDIRECT environment variable to false at build time. When this feature is enabled, the server redirects HTTP requests to HTTPS. For more information about what this entails for each case, see the server-provided documentation.

[build]
  [[build.env]]
    name = BP_PHP_ENABLE_HTTPS_REDIRECT
    value = false

Configure Server Admin for HTTPD

You can override the server admin for httpd from the default of admin@localhost by using the BP_PHP_SERVER_ADMIN environment variable at build time.

[build]
  [[build.env]]
    name = BP_PHP_SERVER_ADMIN
    value = some-admin@localhost

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. For more information on what a PHP session handler is, see the PHP session handler documentation.

To configure a session handler for either Redis or Memcached you must provide a service binding. For more information about how to use service bindings for your platform, see the service binding documentation:

Configuring with kp: kp is for use with Tanzu Build Service which is the easiest way to use Tanzu Buildpacks.
Configuring with pack: pack is one of several Cloud Native Buildpack platforms than can execute builds with Tanzu Buildpacks.

Enable The Session Handler For Redis

To configure a Redis instance session handler, the provided service binding must 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 gcr.io/tanzu-buildpacks/php \
  --env SERVICE_BINDING_ROOT=/bindings \
  --volume <absolute-path-to-binding>:/bindings/php-redis-session

Enable The Session Handler For Memcached

To configure a Memcached instance session handler, the provided service binding must 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 gcr.io/tanzu-buildpacks/php \
  --env SERVICE_BINDING_ROOT=/bindings \
  --volume <absolute-path-to-binding>:/bindings/php-memcached-session

Additional Configuration

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.

Using `project.toml`

[build]
  [[build.env]]
    name = 'BP_LOG_LEVEL'
    value = 'DEBUG'

Passed to the platform

pack build my-app --buildpack gcr.io/tanzu-buildpacks/php \
  --env BP_LOG_LEVEL=DEBUG

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 the configuration documentation.

Override the Start Process Set by the Buildpack

By default, the buildpacks will determine the right start command to run depending on the server that is being used. PHP buildpack users can set custom start processes for their app image by following the instructions in the Procfiles section of the configuration documentation.

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 the configuration documentation.

Access the Software Bill of Materials

The PHP Buildpack includes support for Software Bill of Materials (SBOM). For information about how to access the SBOM supplied by the buildpacks, see the SBOM documentation.

SBOMs are generated for all supported PHP applications.

Buildpack-Set Environment Variables

The PHP CNB sets 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

Example Sample App Builds

How to use in Tanzu Application Platform

How to use in Tanzu Build Service

How to use with pack CLI

Specifying a PHP Version

Set the version using BP_PHP_VERSION

Using project.toml

Passed to the platform

Set the version using a composer.json file

(Unsupported) Set the version using the buildpack.yml

Configure the PHP library directory

Configure PHP with a custom .ini file

Use Extensions

Enable extensions through a custom .ini snippet

Enable extensions through a composer.json

Configure Composer

Set Composer Version

Set Composer Install Options

Set a Custom Composer Vendor Directory

Set the composer.json Path

Set Composer Authentication

Select a Web Server

(Unsupported) Select a web server using the buildpack.yml

Set Server Configuration

Provide your own web server configuration file

Provide httpd specific configuration

Provide nginx specific configuration

Configure FPM Settings

Override Default FPM Configuration

Configure Web Directory

Activate/Deactivate HTTPS Redirect

Configure Server Admin for HTTPD

Enable a Session Handler Via Service Bindings

Enable The Session Handler For Redis

Enable The Session Handler For Memcached

Additional Configuration

Enable DEBUG logging

Using project.toml

Passed to the platform

Install a Custom CA Certificate

Override the Start Process Set by the Buildpack

Set Environment Variables for App Launch Time

Add Custom Labels to the App Image

Access the Software Bill of Materials

Buildpack-Set Environment Variables

PATH

PHP_INI_SCAN_DIR

PHPRC

PHP_API

PHP_EXTENSION_DIR

PHP_HOME

MIBDIRS

APP_ROOT

SERVER_ROOT

COMPOSER

COMPOSER_HOME

COMPOSER_VENDOR_DIRECTORY

COMPOSER_NO_INTERACTION

PHP_FPM_PATH

PHP_HTTPD_PATH

PHP_NGINX_PATH

How to use with `pack` CLI

Set the version using `BP_PHP_VERSION`

Using `project.toml`

Set the version using a `composer.json` file

(Unsupported) Set the version using the `buildpack.yml`

Configure PHP with a custom `.ini` file

Enable extensions through a custom `.ini` snippet

Enable extensions through a `composer.json`

Set the `composer.json` Path

(Unsupported) Select a web server using the `buildpack.yml`

Provide `httpd` specific configuration

Provide `nginx` specific configuration

Enable `DEBUG` logging

Using `project.toml`