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.
To build a sample app locally with this CNB using the pack CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/php/builtin-server pack build my-app --buildpack paketo-buildpacks/php \ --builder paketobuildpacks/builder-jammy-full
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.
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 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 supported versions can be found on the Paketo PHP
Dist releases page.
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.
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
file:
BP_PHP_VERSION="8.0.0"
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.
Specifying the PHP version through buildpack.yml has been
removed as of PHP language family buildpack v1.0.0. To migrate from using
buildpack.yml please set the $BP_PHP_VERSION environment variable.
To add directories to the include_path set in the default php.ini, buildpack users can set the
BP_PHP_LIB_DIR environment variable at build time.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_PHP_LIB_DIR=some-lib-directory
.ini file
If you’d like to configure custom .ini files in addition to the default
php.ini provided by the PHP Dist buildpack, 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 reference docs about the
PHP_INI_SCAN_DIR for more information about
defaults.
There are two ways to enable extensions when using the Paketo PHP Buildpack. The only extensions available for usage at this time are the ones that come with the distribution of PHP.
.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, as
mentioned in the Configure PHP with a custom .ini file
section.
An example snippet could look like:
extension=bz2.so extension=curl.so
composer.json
If you are using Composer as a package manager (see section below), 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": "*",
},
}
The Composer and Composer Install buildpacks allow for user-set configuration options for Composer.
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
on the Paketo Composer releases page. With the pack CLI,
this looks like
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_COMPOSER_VERSION="2.3.1"
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_COMPOSER_INSTALL_OPTIONS="--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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_COMPOSER_INSTALL_GLOBAL="friendsofphp/php-cs-fixer squizlabs/php_codesniffer=*"
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env COMPOSER_VENDOR_DIR="vendor"
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env COMPOSER="some-other-composer.json"
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.
pack build my-app --buildpack paketo-buildpacks/php \
--env COMPOSER_AUTH='{"http-basic": <some-creds>}'
The PHP buildpack supports the use of 3 different web servers:
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_PHP_SERVER="php-server"
Selecting a web server through buildpack.yml configuration has been
removed as of PHP language family buildpack v1.0.0. To migrate from using
buildpack.yml please set the environment variable equivalent instead.
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 PHP Reference documentation for an enumeration of the defaults set for
httpd and nginx.
Additional configuration can also be provided via environment variables.
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.
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.
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.
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).
Check out the PHP Reference documentation for an enumeration of the defaults set for FPM.
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.
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_PHP_WEB_DIR="some-web-dir"
The HTTPS enable feature is an opt-in environment variable configuration
available for PHP apps that use NGINX. It defaults to the disabled state,
and can be enabled by setting the BP_PHP_NGINX_ENABLE_HTTPS environment
variable to true at build time.
When this feature is enabled, the NGINX server is configured to accept
connections in SSL mode, thus enabling it to handle HTTPS requests.
For PHP apps that use HTTPD, you can provide the configuration to enable
HTTPS in a .httpd.conf.d directory at the root of the app. NGINX workloads
have a dedicated environment variable because it’s not possible to override
this configuration from a user-provided config file and needs to be set in
the configuration generated by the buildpack.
pack build my-php-nginx-app --buildpack paketo-buildpacks/php \ --env BP_PHP_NGINX_ENABLE_HTTPS=true
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_PHP_ENABLE_HTTPS_REDIRECT=false
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_PHP_SERVER_ADMIN=some-admin@localhost
By default, the buildpacks will determine the right start command to run depending on the server that is being used. A user can override the start command by using the Paketo Procfile buildpack. Check out the Procfiles section of our configuration docs for details on how to use the buildpack.
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][bp/php-redis-session-handler]. 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.
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 paketo-buildpacks/php \ --env SERVICE_BINDING_ROOT=/bindings \ --volume <absolute-path-to-binding>:/bindings/php-redis-session
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 paketo-buildpacks/php \ --env SERVICE_BINDING_ROOT=/bindings \ --volume <absolute-path-to-binding>:/bindings/php-memcached-session
Users of the PHP buildpack 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.
PHP buildpack users can embed launch-time environment variables in their app image by following the documentation for the Environment Variables Buildpack.
PHP buildpack users can add labels to their app image by following the instructions in the Applying Custom Labels section of our configuration docs.
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.
pack build my-app --buildpack paketo-buildpacks/php \ --env BP_LOG_LEVEL=DEBUG
The PHP buildpack includes support for the software bill of materials (SBOM). Check out the SBOM how-to documentation for details on how to access the SBOM supplied by the buildpacks.
Last modified: April 3, 2024