phpdist

README

PHP Distribution Cloud Native Buildpack

The PHP Distribution CNB provides the PHP binary distribution. The buildpack installs the PHP binary distribution onto the $PATH which makes it available for subsequent buildpacks. These buildpacks can then use that distribution to run PHP tooling. The PHP Web CNB is an example of a buildpack that utilizes the PHP binary.

Integration

The PHP Distribution CNB provides php as a dependency. Downstream buildpacks, like PHP Composer CNB can require the php dependency by generating a Build Plan TOML file that looks like the following:

[[requires]]

  # The name of the PHP dependency is "php". This value is considered
  # part of the public API for the buildpack and will not change without a plan
  # for deprecation.
  name = "php"

  # The PHP buildpack supports some non-required metadata options.
  [requires.metadata]

    # Setting the build flag to true will ensure that the PHP
    # depdendency is available on the $PATH for subsequent buildpacks during
    # their build phase. If you are writing a buildpack that needs to run PHP
    # during its build process, this flag should be set to true.
    build = true

    # Setting the launch flag to true will ensure that the PHP
    # dependency is available on the $PATH for the running application. If you are
    # writing an application that needs to run PHP at runtime, this flag should
    # be set to true.
    launch = true

    # Optional. If not provided, the buildpack will provide the default version from buildpack.toml.
    # To request a specific version, you can specify a semver constraint such as "8.*", "8.0.*",
    # or even "8.0.4".
    version = "8.0.4"

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh

This builds the buildpack's Go source using GOOS=linux by default. You can supply another value as the first argument to package.sh.

License

This buildpack is released under version 2.0 of the Apache License.

Run Tests

To run all unit tests, run:

./scripts/unit.sh

To run all integration tests, run:

./scripts/integration.sh

Buildpack Configurations

PHP Version

Specifying the PHP Dist version through buildpack.yml configuration is deprecated.

To migrate from using buildpack.yml please set the $BP_PHP_VERSION environment variable at build time either directly (ex. pack build my-app --env BP_PHP_VERSION=7.3.*) or through a project.toml file

# this allows you to specify a version constraint for the `php` depdendency
# any valid semver constaints (e.g. 7.*) are also acceptable
$BP_PHP_VERSION="7.3.*"

PHP library directory

The PHP library directory is available to PHP via an include path in the PHP configuration. By default it is set to /workspace/lib and can be overriden by setting the BP_PHP_LIB_DIR environment variable at build-time.

$BP_PHP_LIB_DIR="some-directory"

Provide custom .ini files

Custom .ini files can be provided from users to amend the default php.ini file. This can be done by placing an ini-type configuration file inside <application directory>/.php.ini.d/. Its path will be made available via the PHP_INI_SCAN_DIR.

Debug Logs

For extra debug logs from the image build process, set the $BP_LOG_LEVEL environment variable to DEBUG at build-time (ex. pack build my-app --env BP_LOG_LEVEL=DEBUG or through a project.toml file.

Documentation

Index

• Constants
• Variables
• func Build(dependencies DependencyManager, files FileManager, ...) packit.BuildFunc
• func Detect() packit.DetectFunc
• type BuildPlanMetadata
• type DependencyManager
• type Environment
  • func NewEnvironment() Environment
  • func (e Environment) Configure(layer packit.Layer, extensionsDir string, defaultIniPath string, ...) error
• type EnvironmentConfiguration
• type FileManager
• type PHPFileManager
  • func NewPHPFileManager() PHPFileManager
  • func (f PHPFileManager) FindExtensions(layerRoot string) (string, error)
  • func (f PHPFileManager) WriteConfig(layerRoot, cnbPath string, data PhpIniConfig) (string, string, error)
• type PhpIniConfig
• type SBOMGenerator

Constants

const (
	DepKey           = "dependency-sha"
	PHPDependency    = "php"
	UserProvidedPath = ".php.ini.d"
)

Variables

var EntryPriorities = []interface{}{
	"BP_PHP_VERSION",
	"composer.lock",
	"composer.json",
	"default-versions",
}

Functions

func Build

func Build(dependencies DependencyManager,
	files FileManager,
	environment EnvironmentConfiguration,
	sbomGenerator SBOMGenerator,
	logger scribe.Emitter,
	clock chronos.Clock) packit.BuildFunc

Build will return a packit.BuildFunc that will be invoked during the build phase of the buildpack lifecycle.

Build will find the right php dependency to install, install it in a layer, and generate a Bill-of-Materials. On rebuilds, it reuses the cached dependency if the SHA256 of the requested version matches the SHA256 of the cached version. Build also sets up a default php.ini configuration.

func Detect

func Detect() packit.DetectFunc

Detect will return a packit.DetectFunc that will be invoked during the detect phase of the buildpack lifecycle.

Detect always passes, and will contribute a Build Plan that provides php.

Types

type BuildPlanMetadata

type BuildPlanMetadata struct {
	Version       string `toml:"version"`
	VersionSource string `toml:"version-source"`
}

BuildPlanMetadata is the buildpack specific data included in build plan requirements.

type DependencyManager

type DependencyManager interface {
	Resolve(path, id, version, stack string) (postal.Dependency, error)
	Deliver(dependency postal.Dependency, cnbPath, layerPath, platformPath string) error
	GenerateBillOfMaterials(dependencies ...postal.Dependency) []packit.BOMEntry
}

DependencyManager defines the interface for picking the best matching dependency, installing it, and generating a BOM.

type Environment

type Environment struct {
}

Environment sets build- and launch-time environment variables to properly install and configure PHP.

func NewEnvironment

func NewEnvironment() Environment

func (Environment) Configure

func (e Environment) Configure(layer packit.Layer, extensionsDir string, defaultIniPath string, iniScanDirs []string) error

Configure sets build- and launch-time environment variables on the layer passed as input. Proper values for the environment variables are determined by the layer path, and the other paths provided as inputs. See PHP documentation for an explanation of the environment variables' significance.

type EnvironmentConfiguration

type EnvironmentConfiguration interface {
	Configure(layer packit.Layer, extensionsDir, defaultIni string, scanDirs []string) error
}

EnvironmentConfiguration defines the interface for setting build- and launch-time environment variables on the layer.

type FileManager

type FileManager interface {
	FindExtensions(layerRoot string) (string, error)
	WriteConfig(layerRoot, cnbPath string, data PhpIniConfig) (defaultConfig string, buildpackConfig string, err error)
}

FileManager defines the interface for manipulating files in the PHP installation in the build container.

type PHPFileManager

type PHPFileManager struct{}

PHPFileManager finds, copies, and creates files necessary for a proper PHP installation.

func NewPHPFileManager

func NewPHPFileManager() PHPFileManager

func (PHPFileManager) FindExtensions

func (f PHPFileManager) FindExtensions(layerRoot string) (string, error)

FindExtensions checks a path relative to the layer passed as input where it expects extensions to be pre-installed. It fails if a directory in the expected location does not exist.

func (PHPFileManager) WriteConfig

func (f PHPFileManager) WriteConfig(layerRoot, cnbPath string, data PhpIniConfig) (string, string, error)

WriteConfig generates a default PHP configuration and stores the resulting *.ini files in the layer provided as input.

type PhpIniConfig

type PhpIniConfig struct {
	IncludePath string
	// include_path = "{{.PhpHome}}/lib/php:{{.AppRoot}}/{{.LibDirectory}}"
	ExtensionDir string
	// extension_dir = "{{.PhpHome}}/lib/php/extensions/no-debug-non-zts-{{.PhpAPI}}"
	Extensions     []string
	ZendExtensions []string
}

PHPIniConfig represents the data that will be inserted in a templated php.ini file.

type SBOMGenerator

type SBOMGenerator interface {
	GenerateFromDependency(dependency postal.Dependency, dir string) (sbom.SBOM, error)
}