A buildpack to deploy PHP applications to Cloud Foundry based systems, such as a cloud provider or your own instance.
Official buildpack documentation can be found here: php buildpack docs.
To build this buildpack, run the following commands from the buildpack's directory:
-
Source the .envrc file in the buildpack directory.
source .envrcTo simplify the process in the future, install direnv which will automatically source
.envrcwhen you change directories. -
Install buildpack-packager
go install github.com/cloudfoundry/libbuildpack/packager/buildpack-packager@latest
-
Build the buildpack
buildpack-packager build [ --cached ]
Alternatively, use the package script:
./scripts/package.sh [ --cached ]
-
Use in Cloud Foundry
Upload the buildpack to your Cloud Foundry and optionally specify it by name
cf create-buildpack [BUILDPACK_NAME] [BUILDPACK_ZIP_FILE_PATH] 1 cf push my_app [-b BUILDPACK_NAME]
Find our guidelines here.
Buildpacks use the Switchblade framework for running integration tests against Cloud Foundry. Before running the integration tests, you need to login to your Cloud Foundry using the cf cli:
cf login -a https://api.your-cf.com -u name@example.com -p pa55woRDNote that your user requires permissions to run cf create-buildpack and cf update-buildpack. To run the integration tests, run the following commands from the buildpack's directory:
-
Source the .envrc file in the buildpack directory.
source .envrcTo simplify the process in the future, install direnv which will automatically source .envrc when you change directories.
-
Run unit tests
./scripts/unit.sh
-
Run integration tests
./scripts/integration.sh
More information can be found on Github switchblade.
The project is broken down into the following directories:
bin/- Executable shell scripts for buildpack lifecycle:detect,supply,finalize,release,start,rewritesrc/php/- Go source code for the buildpackdetect/- Detection logicsupply/- Dependency installation (PHP, HTTPD, Nginx)finalize/- Final configuration and setuprelease/- Release informationextensions/- Extension system (composer, newrelic, dynatrace, appdynamics, sessions)config/- Configuration managementoptions/- Options parsinghooks/- Lifecycle hooksintegration/- Integration testsunit/- Unit tests
defaults/- Default configuration filesfixtures/- Test fixtures and sample applicationsscripts/- Build and test scripts
This buildpack uses Cloud Foundry's libbuildpack framework and is written in Go. The buildpack lifecycle consists of:
-
Detect (
bin/detect→src/php/detect/) - Determines if the buildpack should be used by checking for PHP files orcomposer.json -
Supply (
bin/supply→src/php/supply/) - Installs dependencies:- Downloads and installs PHP
- Downloads and installs web server (HTTPD or Nginx)
- Runs extensions in "configure" and "compile" phases
- Installs PHP extensions
- Runs Composer to install application dependencies
-
Finalize (
bin/finalize→src/php/finalize/) - Final configuration:- Configures web server (HTTPD or Nginx)
- Sets up PHP and PHP-FPM configuration
- Copies rewrite and start binaries to
.bp/bin/ - Generates preprocess scripts that will run at startup
- Prepares runtime environment
-
Release (
bin/release→src/php/release/) - Provides process types and metadata
-
Rewrite (
bin/rewrite→src/php/rewrite/cli/) - Configuration templating at runtime:- Called during application startup (before services start)
- Replaces template patterns in configuration files with runtime environment variables
- Supports patterns:
@{VAR},#{VAR},@VAR@,#VAR - Allows configuration to adapt to the actual runtime environment (ports, paths, etc.)
- Rewrites PHP, PHP-FPM, and web server configs
-
Start (
bin/start→src/php/start/cli/) - Process management:- Runs preprocess commands (including rewrite operations)
- Launches all configured services (PHP-FPM, web server, etc.) from
.procsfile - Monitors all processes
- If any process exits, terminates all others and restarts the application
The buildpack includes several built-in extensions written in Go:
- composer - Downloads, installs and runs Composer. Automatically detects PHP version requirements from
composer.jsonand validates against locked dependencies. - newrelic - Downloads, installs and configures the NewRelic agent for PHP
- dynatrace - Downloads and configures Dynatrace OneAgent. Looks for a bound service with name
dynatraceand credentials containingapiurl,environmentid, andapitoken. - appdynamics - Downloads and configures AppDynamics agent
- sessions - Configures PHP to store session information in a bound Redis or Memcached service instance
Extensions implement the Extension interface defined in src/php/extensions/extension.go:
type Extension interface {
Name() string
ShouldCompile(ctx *Context) (bool, error)
Configure(ctx *Context) error
Compile(installer Installer) error
PreprocessCommands(ctx *Context) ([]string, error)
ServiceCommands(ctx *Context) (map[string]string, error)
ServiceEnvironment(ctx *Context) (map[string]string, error)
}Extension Lifecycle:
- Configure - Called early to modify buildpack configuration (e.g., set PHP version, add extensions)
- Compile - Main extension logic, downloads and installs components
- ServiceEnvironment - Contributes environment variables
- ServiceCommands - Contributes long-running services
- PreprocessCommands - Contributes commands to run before services start
For examples, see the built-in extensions in src/php/extensions/.
Note: Custom user extensions from .extensions/ directory are not currently supported in the Go-based buildpack. This feature may be added in a future release.
Join the #buildpacks channel in our Slack community
This project is managed through GitHub. If you encounter any issues, bug or problems with the buildpack please open an issue.
The project backlog is on Pivotal Tracker