PHP

Info

This documentation is adapted for Miget purposes and is based on information from the Paketo PHP Buildpack documentation.

This documentation explains how to use the Paketo buildpacks with Miget to build PHP applications for several common use-cases. For more in-depth description of the buildpacks’ behavior and configuration see the Paketo Python Buildpack. For more in-depth description of the buildpack’s behavior and configuration see the Paketo PHP Buildpack Reference documentation.

If your intention is to deploy an app using a Dockerfile, please refer to the Dockerfile page for guidance and best practices.

Prerequisites

The pack CLI is used throughout the examples.

Examples assume that the Paketo Base builder is the default builder:

$ pack config default-builder paketobuildpacks/builder-jammy-base

Example App

Info

A demo instance of this app is hosted at php.onmiget.com.

Build

$ git clone git@github.com:migetapp/php-hello-world.git
$ cd php-hello-world
$ pack build php-hello-world

Run

$ docker run -p 5000:5000 -e PORT=5000 php-hello-world

The example app should now be running on localhost:5000.

Configure PHP

Install a Specific PHP Version

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.

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

Configure PHP with a custom `.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.

Use Extensions

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.

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, as mentioned in the Configure PHP with a custom .ini file section.

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 (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": "*",
    },
}

Configure Composer

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

Set the 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 on the Paketo Composer releases page. For Miget builder, the Environment Variable set under Settings -> Config Vars: BP_COMPOSER_VERSION=2.3.1

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

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.

BP_COMPOSER_INSTALL_GLOBAL="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.

COMPOSER_VENDOR_DIR="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.

COMPOSER="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.

COMPOSER_AUTH='{"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.

BP_PHP_SERVER="php-server"

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

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

BP_PHP_WEB_DIR="some-web-dir"

Enable/disable HTTPS

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.

BP_PHP_NGINX_ENABLE_HTTPS=true

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.

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

BP_PHP_SERVER_ADMIN=some-admin@localhost

Override the start process

Warning

This isn't currently available at Miget. We are working on it.

Enable a session handler via service bindings

Warning

This isn't yet fully supported at Miget. We are working on mouting Miget Volumes for the builder environment

The PHP Buildpack supports using session handlers for Memcached and Valkey 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.

Enable the session handler for Valkey

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	Valkey instance IP address
`port`	Default 6379	no	Valkey instance port
`password`	Omitted if unset	no	Valkey instance password

To build at Miget with the binding, you need to create a Volume as /bindings and store your credential there. Next, add Variable under Settings -> Config Vars: SERVICE_BINDING_ROOT=/bindings

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