Migrating to the Tanzu PHP Buildpack

Overview

This topic provides a migration guide from the v2 PHP Buildpack for Tanzu Application Service for VMs to the Tanzu PHP Buildpack. By following this guide, you can migrate your existing PHP applications running on Tanzu Application Service for VMs to Tanzu Application Service for Kubernetes or 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. This configuration can be moved to new locations as described below:

App configuration in .bp-config/httpd/extra/httpd-modules.conf should be moved to httpd.conf.d/httpd-modules.conf.
PHP and Zend extensions defined in in .bp-config/php.ini.d/<filename>.ini should be moved to .php.ini.d/php.ini.
Configuration defined in .bp-config/php/fpm.d/* should be moved to .php.fpm.d/*.

Breaking changes in the Tanzu PHP Buildpack

The buildpack will not automatically move files served by the webserver (e.g. 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, you should move it manually, or leverage the php.webdirectory field in the buildpack.yml file to specify an alternative that the buildpack will follow.
The detection phase will fail if the user-provided version of PHP is not available in the buildpack.
The detection phase will fail if the value of php.webserver in buildpack.yml is invalid.
The build phase will fail if a composer.json file is present without a composer.lock file also being present.
The composer CLI will not be 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, you can specify a custom location using the composer.json_path field in your buildpack.yml file.
The buildpack will successfully build an application even if there are unsupported extensions enabled in a .php.ini.d/*.ini file. In this case, PHP will raise 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 will be ignored during launch.

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

Buildpack extensions included in a .extensions directory will not be supported.
The v3 PHP Buildpack will not include configuration support for the geoip extension. The configuration helpers from the v2 PHP Buildpack are not available. However, the geoip extension can still be configured via the .php.ini.d/php.ini file.