Migrate to the Tanzu PHP Buildpack

This topic tells you how to migrate from the v2 PHP Buildpack for Tanzu Application Service for VMs to the Tanzu PHP Buildpack. Use this topic to migrate your existing PHP applications running on Tanzu Application Service for VMs to Tanzu Build Service.

Partner Integrations

The v2 PHP Buildpack bundled a number of third-party integrations with partner utilities including Appdynamics, Contrast Security, Dynatrace, New Relic, Synopsys, and Snyk. The v3 PHP Buildpack does not yet include these integrations.

Application Source Changes

Setting a version of PHP

Define a buildpack.yml file in your application source to specify a version of the PHP distribution as follows:

php:
  # Use the version field to specify a version constraint
  # for the PHP dependency. Any valid semver constraint
  # (e.g. 1.2.*) is acceptable.
  version: 7.*

Overriding the default web directory

Define a buildpack.yml file in your application source to specify the webdirectory used by PHP as follows:

php:
  # Use the webdirectory field to specify the root directory of the
  # files served by the web server, if applicable.
  webdirectory: “htdocs”

Configuring `composer`

Define a buildpack.yml file in your application source to specify the configuration of composer as follows:

composer:
  # Use the version field to specify a version constraint
  # for the composer dependency. Any valid semver constaint
  # (e.g. 1.* and 1.10.*) is acceptable.
  version: 1.10.*

  # Use the install_options field to specify extra options
  # to pass to the composer installation process. The default
  # value is ["--no-dev"]
  install_options: ["--no-dev"]

  # Use the vendor_directory field to specify the location
  # of vendored dependencies for composer to use during
  # installation. The default value is "vendor"
  vendor_directory: vendor

  # Use the json_path field to specify the location of the
  # composer.json file. The default value is the root directory
  # of the application source code.
  json_path: composer

  # Use the install_global field to force the build process
  # to run `composer global` with a specified set of arguments.
  install_global: ["list", "of", "install", "options"]

New locations for PHP and Zend extension configuration

The v3 PHP Buildpack will no longer search for configuration in the .bp-config directory. You can move this configuration to new locations as follows:

Move the app configuration in .bp-config/httpd/extra/httpd-modules.conf to httpd.conf.d/httpd-modules.conf.
Move the PHP and Zend extensions defined in .bp-config/php.ini.d/<filename>.ini to .php.ini.d/php.ini.
Move the configuration defined in .bp-config/php/fpm.d/* to .php.fpm.d/*.

Breaking changes in the Tanzu PHP Buildpack

The buildpack does not automatically move files served by the web server, such as index.php, that are in the application root into a directory called htdocs. If your program entrypoint is not located in a directory called htdocs, move it manually or use the php.webdirectory field in the buildpack.yml file to specify an alternative.
The detection phase fails if the user-provided version of PHP is not available in the buildpack.
The detection phase fails if the value of php.webserver in buildpack.yml is invalid.
The build phase fails if a composer.json file is present without a composer.lock file also being present.
The composer CLI is not installed unless a composer.json and composer.lock file are both present in the application source code. If these files are not present in the root of the application source code, specify a custom location using the composer.json_path field in your buildpack.yml file.
The buildpack successfully builds applications even if there are unsupported extensions enabled in a .php.ini.d/*.ini file. In this case, PHP raises a runtime error when those unsupported extensions are initialized.

Unsupported Workflows

The following workflows are not currently supported in the Tanzu PHP Buildpack:

A .profile.d directory containing scripts to be run just before application launch is not currently supported. These scripts are ignored during launch.

The following workflows existed in the v2 PHP Buildpack and are not supported in the Tanzu PHP Buildpack:

Buildpack extensions included in a .extensions directory are not supported.
The v3 PHP Buildpack does not include configuration support for the geoip extension. The configuration helpers from the v2 PHP Buildpack are not available. However, you can configure the geoip extension through the .php.ini.d/php.ini file.