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

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

Please note that the Tanzu PHP buildpack is only compatible with the Full ClusterBuilder (in TAP), 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 TAP

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

  1. We'll now trigger an image build in the my-apps namespace by running:
tanzu apps workload apply --file workload.yaml --namespace my-apps

3. You're done with build! You can view the result with:

tanzu apps workload get httpd-sample --namespace my-apps

### <a id="how-to-use-in-tbs"></a> How to use in TBS

The PHP buildpack is only available in the `full` descriptor of TBS.  Use `kp
image create` to create an image resource.  For more details, see [Build
Service
Documentation](https://docs.vmware.com/en/Tanzu-Build-Service/1.6/vmware-tanzu-build-service/GUID-managing-images.html#image-resources)

### <a id="how-to-use-with-pack"></a> How to use with `pack` CLI

The [pack CLI](https://github.com/buildpacks/pack) can be used to build your
application image.

1. From the app directory, build the image with `pack`:

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


2. Once the build has succeeded, run the image:

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


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


## <a id="specifying-php-version"></a> 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 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](https://github.com/buildpacks/spec/blob/main/extensions/project-descriptor.md)
file:

BP_PHP_VERSION="8.0.0"


#### 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" } }


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 v3.0.0.  To migrate from using
`buildpack.yml` please set the `$BP_PHP_VERSION` environment variable.

## <a id="configure-php-library"></a> Configure the PHP library directory

To add directories to the [`include_path`](https://www.php.net/manual/en/ini.core.php#ini.include-path) set in the default `php.ini`, buildpack users can set the
`BP_PHP_LIB_DIR` environment variable at build time.
```toml
[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.

Check out the Buildpack-Set Environment Variables section for more information about the default PHP_INI_SCAN_DIR value.

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

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

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.

[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 docs.

[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: Using 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. Check out the Paketo 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 section below).

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

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

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.

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

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.

[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. 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. Check out the service binding documentation for more information about how to use service bindings for your platform:

  • 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 just 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 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 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 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 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.

Via project.toml

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

Passed to 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 our configuration docs.

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

Access the Software Bill of Materials

The PHP Buildpack includes support for Software Bill of Materials (SBOM). Check out the SBOM documentation for details on how to access the SBOM supplied by the buildpacks.

SBOMs will be 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

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
check-circle-line exclamation-circle-line close-line
Scroll to top icon