paketo-buildpacks / php-dist

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.

php-dist's Issues

Failure: Update GitHub config workflow

Update GitHub config workflow failed.

I cannot find the list of modules php modules that come with the distribution

The release notes should clearly state what are all the modules that come with the php interpreter in the distribution. Does this contain phpiredis? Does this contain mongodb? This buildpack cannot be fully used to its potential without a well documented list of modules that are part of the php distribution provided by this buildpack.

Consume PHP dependency from the dep-server

Per paketo-buildpacks/dep-server#45, we should start consuming the PHP dependency from the dep-server (https://api.deps.paketo.io/v1/dependency?name=<dependency>) instead of the https://buildpacks.cloudfoundry.org/dependencies/<dependency>/... location we currently get the dependencies from.

This will make the dependency publishing/consumption process more transparent than the process we use for the dependencies available via the dependency-builds pipeline.

We have already done this switch-over in the Node Engine and Yarn Buildpacks. The outline of what this work will entail can be found in the dep-server issue linked at the top.

Failure: Update Dependencies workflow

Update Dependencies From Metadata workflow failed.

Use PHP-provided `php.ini` as default

Context

In the restructure work (#324), the PHP Dist buildpack is responsible for configuring the default php.ini file.
The PHP Dist buildpack (as it exists in #341 for the restructure work) creates 2 php.ini files:

1. A static default php.ini file (config/default.ini)
2. A go-templated buildpack-provided php.ini (config/buildpack.ini)

Issue

This issue is to figure out how we can access the default php.ini file that ships with the PHP distribution, and use that in place of the static config/default.ini file. This is necessary because the default configuration might change slightly from version to version, so it may be problematic to use the same template for every version as we currently do.

The PHP source (from https://www.php.net/distributions/php-VERSION.tar.gz) we use to compile the buildpack-ready PHP distribution contains a php.ini-production file which could be used as the default php.ini. We should figure out we can retrieve that php.ini in the compiled PHP version, and swap that file in for the config/default.ini in the buildpack.

Acceptance

In order to close out this issue, I would expect that the default php.ini file used in the buildpack is taken from the PHP dependency from https://deps.paketo.io/php/... for all PHP versions we support in the buildpack.

Failure: Push Buildpackage workflow

Push Buildpackage workflow failed.

Implement Dependency RFC 0004 for php

Implement Dependency Management RFC Phase 1 for php. Check out the RFC for more details and background.

1. Determine dependency source strategy

Background

When possible, dependencies should be used directly from upstream, rather than undergoing any additional compilation or modifications performed by Paketo-maintained code. For each dependency, the corresponding buildpack maintainer group will decide if the dependency can be used directly from upstream, and must identify the location from which the dependency will be pulled from. Some of the Paketo Java buildpacks perform directory stripping during the buildpack build process itself. This could be a viable alternative to performing directory modifications during the dependency management process for maintainers to consider.

• Determine whether the dependency can be used directly from its upstream, rather than undergoing additional compilation/modification.

• If using directly from upstream, note where dependencies will come from
• If compiled or modified, note the decision for this

• Document decision in a language-family level RFC. This decision can be combined in the RFC with the decision made for other buildpacks in the language family.

2. Version retrieval and metadata generation code

Please refer to the retrieval RFC section on version retrieval for details around the API and background.

• Create retrieval code for the dependency

• Will live in the buildpack under: dependency/retrieval/
• Per the RFC, this will be a combination of (1) discovering new dependency versions based on the buildpack.toml, and (2) generating metadata for each new version.
• Note : Per the RFC caveat - if the dependency is to be compiled, the SHA256 and URI field from the metadata should be omitted in this step.

3. Compilation code (if needed)

If the dependency will be compiled/modified, then refer to the compilation RFC section for API details and background.

• Create compilation action

• Will live in the buildpack under: dependency/actions/compile/

4. Dependency testing (optional)

It's up to maintainer discretion if the dependency will be tested. It's recommended to test the dependency if it's been compiled. Check out the testing RFC section for details.

• Add tests for dependency

• Will live in the buildpack under: dependency/test.

5. Makefile Setup

When using the generalized workflows for dependency management down the line, version retrieval and dependency testing will be executed via a Makefile in order to provide the workflow a standardized way to run the code, regardless of what language it was written in. Check out the RFC section for what this should look like.

• Add Makefile

• Will live in the buildpack at: dependency/Makefile

6. Leveraging the new code

This issue serves to set up all the main logic for the dependency management. The work to actually leverage this code and migrate off of the dep-server will be completed in a separate issue once workflows and infrastructure is set up.

Failure: Update Dependencies workflow

Update Dependencies From Metadata workflow failed.

Remove version 7.3

The v7.3 version line of PHP is out of support as of November 2021, according to the schedule on https://www.php.net/supported-versions.php.

Although the listed deprecation date in the buildpack.toml is 2024, it has been determined that this date was calculated incorrectly in our code. As a result, we should remove the version line, and also update the given deprecation dates for all other versions in the buildpack.toml.

Note: this version will be removed in the next minor release of the PHP buildpack. cc @paketo-buildpacks/php-maintainers

Add deprecation warning for `buildpack.yml` usage

Per paketo-buildpacks/rfcs#58 (from RFC 0026) we are switching over the use of buildpack.yml configurations to environment variable-set configurations.

We should start this process for PHP by emitting a deprecation warning via log output about using the buildpack.yml setting that says:

WARNING: Setting the PHP version through buildpack.yml will be deprecated soon in PHP Dist Buildpack v1.0.0.

The v1.0.0 buildpack release will support setting the version through an environment variable instead.

We accomplish this in other buildpacks which can be used as an example for this issue.

Failure: Create Draft Release workflow

Create Draft Release workflow failed.

Refactor dependency management workflow

In an effort to make PHP compatible with Jammy, we've copied the binary-builder code from dep-server directly into this buildpack's dependency management workflow. See this comment for more context. This is not ideal because the binary-builder code is superfluous and hard to maintain.

Keeping the binary-builder code as is also created sudo-related issues that made it difficult to run commands within the compilation container. As a result, a docker user was created as a hack. This is not a long term solution.

Acceptance Criteria:

• remove binary-builder directory from dependency/actions/compile
• remove docker user form sudo-ers group and remove --env PASSWORD=docker from action.yml

OpenSSL extension is missing

What happened?

I'm building a builder that uses php-dist and php-composer, some of my buildpacks require OpenSSL to be installed but it's by default.

• What were you attempting to do?

1 - To fetch HTTPS-secured content using file_get_contents function.
2 - Install missing dependencies (not originally present, but detected later) using composer require

• What did you expect to happen?

• I can instruct the builder to include the extension during the build process ( related to #118 )
• The script can be executed without errors.

• What was the actual behavior? Please provide log output, if possible.

OpenSSL is not installed

a) my script

warning: file_get_contents(): Unable to find the wrapper "https" - did you forget to enable it when you configured PHP?

b) composer (called later)

[builder]   composer require --dev brianium/paratest
[builder]   The openssl extension is required for SSL/TLS protection but is not available. If you can not enable the openssl extension, you can disable this error, at your own risk, by setting the 'disable-tls' option to true.  

Build Configuration

# [...]
[[order]]
  [[order.group]]
    id = "paketo-buildpacks/php-dist"
    version = "0.2.0"
  [[order.group]]
    id = "paketo-buildpacks/php-composer"
    version = "0.1.2"
  [[order.group]]
    id = "paketo-buildpacks/php-web"
    version = "0.0.138"

• What platform (pack, kpack, tekton buildpacks plugin, etc.) are you
  using?

pack version 0.17.0+git-d9cb4e7.build-2045

• What buildpacks are you using? Please include versions.

[[buildpacks]]
  uri = "docker://gcr.io/paketo-buildpacks/php-dist"
  version = "0.2.0"

[[buildpacks]]
  uri = "docker://gcr.io/paketo-buildpacks/php-web"
  version = "0.0.138"

[[buildpacks]]
  uri = "docker://gcr.io/paketo-buildpacks/php-composer"
  version = "0.1.2"

• What builder are you using? If custom, can you provide the output from pack inspect-builder <builder>?

docker.io/paketobuildpacks/builder:full-cf

• Can you provide a sample app or relevant configuration (buildpack.yml,
  nginx.conf, etc.)?

Checklist

• [ x ] I have included log output.
• [ x ] The log output includes an error message.
• [ x ] I have included steps for reproduction.

Failure: Go get update workflow

Go get update workflow failed.

Please configure GITBOT

Pivotal provides the Gitbot service to synchronize issues and pull requests made against public GitHub repos with Pivotal Tracker projects.

If you do not want to use Pivotal Tracker to manage this GitHub repo, you do not need to take any action.

If you are a Pivotal employee, you can configure Gitbot to sync your GitHub repo to your Pivotal Tracker project with a pull request.

Steps:

• Add the Toolsmiths-Bots team to have admin access to your repo
• Add the cf-gitbot ([email protected]) user to have owner access to your Pivotal Tracker project
• Create new branch in this repo: cfgitbot-config (an ask+cf@ ticket is the fastest way to get write access if you get a 404)
• Add your new repo and or project to config-production.yml file
• Submit a PR, which will get auto-merged if you've done it right. Detailed steps here

If you are not a pivotal employee, you can request that [email protected] set up the integration for you.

You might also be interested in configuring GitHub's Service Hook for Tracker on your repo so you can link your commits to Tracker stories. You can do this yourself by following the directions at:

https://www.pivotaltracker.com/help/articles/github_integration/

If there are any questions, please reach out to [email protected].

Support PHP 8.2

Currently, the buildpack does not support PHP 8.2. We should add support for it, as it is available.
See https://www.php.net/releases/8.2/en.php for details

Add integration tests

This buildpack is missing any integration testing using pack and this buildpack to produce a container image.

We should add some simple integration tests that just assert that the php binary is added to an output image & that it correctly functions on the bionic stack.

Support PHP 8.3 / Remove 8.0

PHP 8.3 was released on 11/23/23. We should support it in the buildpack.
While we're at it, we should remove support for PHP 8.0 which is now out of support

https://www.php.net/supported-versions.php

IMPORTANT NOTICE: End of Support for PHP versions 7.2.x after 2020-12-02

The first release of the PHP Dist buildpack after December 2, 2020 will no longer include PHP versions 7.2.x. These PHP versions will no longer be supported upstream.[1] Please migrate your PHP apps to supported versions of PHP before that time.

Note: As 7.2.x is the current default version of PHP in the buildpack, the default PHP version will be updated to 7.4.x as a part of this removal. If you’d like to use a different PHP version, please configure your application to select that version[2].

As always, the buildpacks team is happy to answer questions you may have about this deprecation in the Paketo Buildpacks Slack.

[1] - https://www.php.net/supported-versions.php
[2] - https://paketo.io/docs/buildpacks/language-family-buildpacks/php/

php cli is not in $PATH

Expected Behavior

I can use the php cli inside my image:

<?php
#!/usr/bin/env php
echo "Hello world";

Current Behavior

/layers/paketo-buildpacks_php-dist/php/bin/php -v
PHP 8.1.7 (cli) (built: Jun 15 2022 09:21:34) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.7, Copyright (c) Zend Technologies
cnb@c2a50c734a25:/workspace$ echo $PATH
/cnb/process:/cnb/lifecycle:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
cnb@c2a50c734a25:/workspace$ php -v
bash: php: command not found

Possible Solution

Add the layer to the PATH, or install in a location that is in PATH already.

Steps to Reproduce

Discovered this while fiddling with paketo-buildpacks/composer-install#46

Motivations

Lots of projects distribute command line tools that rely on the php (cli) to be in PATH. These are broken now.

In addition, there are so-called phars, which are php apps distributed as an executable archive. They also rely on the cli to be in PATH.

Make available extensions discoverable

Currently, we point users who want to know what extensions are available at the old V2 compilation code lists of extensions. It would be great if we had a better way to make the list of extensions available for each version we support, right here in the buildpack. Ideally, in the release notes.

We should look into if there's a nice way to get this list from the PHP artifacts we support and add it to the release notes somehow, or at a minimum give users a simpler way to understand extension options.

Remove buildpack.yml support and warnings

Currently, the buildpack supports buildpack.yml configuration and also emits logs warning against the deprecation of this feature.

We should remove support for buildpack.yml support and warning logs and release the buildpack. This release should make it into the v1.0.0 release of the PHP language family buildpack.

Restructure buildpack: PHP Dist

Context

Per PHP RFC 0001 we are restructuring the PHP language family of buildpacks to make them more modular, up-to-date, and as a result, maintainable.

This buildpack currently provides php, the PHP binary distribution onto the $PATH, and was fairly recently rewritten using the packit library.

Issue

Since this buildpack is already using packit, and is already modular, this issue is primarily
to do two things:

• Per the RFC, this buildpack should generate a default configuration file (php.ini). Additionally, the PHP_INI_SCAN_DIR and PHPRC environment variables should be set. Check out this conversation for additional context.

• Modify this buildpack to use Buildpack API 0.7. It currently uses Buildpack API 0.4, so some implementation updates will be needed.

  Check out CNB API migration guides as well as buildpacks in other language families that perform similar tasks on API 0.7 (such as the Node Engine buildpack)

• Add a [[buildpack.licences]] section to the buildpack.toml.

• Support env var configuration instead of buildpack.yml (See PHP buildpack RFC #2)

Acceptance

This issue can be considered accepted if:

1. The buildpack API is 0.7
2. I can add locally use this version of the PHP Dist buildpack in the PHP language family buildpack, and successfully build all of the apps we currently support.

Failure: Approve bot PR workflow

Approve bot PR workflow failed.

Update README

Update the README to reflect newest changes to the buildpack as of #341

Compile dependency on actual stack images

The dependency that this buildpack provides is compiled on an image that isn't actually the stack image. This could result in subtle bugs - like features not being enabled or enabled features not being available at run-time - due to differences in configuration and available libraries. We should compile the dependency on the actual stack base image rather than a similar image.

Conform to RFC RFC0043: Reproducible builds

To conform to RFC0043 this buildpack should ensure that builds are reproducible. Specifically it should not include a built_at metadata field. In the tests that leverage this field to assert layer reuse, we should instead compare layer SHA values across rebuilds.

See also the tracking issue: paketo-buildpacks/rfcs#165.

Repackage php dependency so as to not contain symlink references to external locations

Background

Recently packit decided to validate against zip slipping (paketo-buildpacks/packit#158). So any dependency that can potentially access parts of the file system outside of the target directory is a risk and its installation would result in an error. Thus, updates to packit (#230) and occam (#220) have been failing.

Proposal

Repackage the PHP Dist tarball so that it does not have symlink references to external file locations.
See this thread (paketo-buildpacks/packit#161 (comment)) for further info.
PRs updating packit (#230) and occam (#220) should pass once this is resolved.

Conform to Paketo RFC0038: Generate SBOM on filesystem as well as label metadata

To implement Paketo RFC0038, this buildpack will need to store SBOM information the filesystem in addition to the layer metadata. The RFC outlines what these files are and what they should contain.

See also paketo-buildpacks/php#517.

See the nodejs buildpack integration tests for an example on how to test this.

Support PHP 8.1

PHP version 8.1.* is available as of 25 Nov 2021, and we should consider supporting it eventually, especially since we wil be ending support for verion 7.3 in #335.
Currently, this version's availability in the dep-server is blocked on paketo-buildpacks/dep-server#133, which is a blocker to this issue. Once that is resolved, we can consider introducing the dependency constraint for 8.1 to the buildpack.toml, modify the buildpack/tests as needed, and start receiving version bumps via our automation.

Php version - improper constraint

What happened?

• What were you attempting to do?

• • I'm trying to use php buildpack with a Laravel application, but I got an error regarding the PHP version constraint specified for it.

• What did you expect to happen?

• • Php buildpack successfully accepts the candidate version suggested in composer.lock file

• What was the actual behavior? Please provide log output, if possible.

Paketo PHP Buildpack 0.2.0
  Resolving PHP version
    Candidate version sources (in priority order):
      composer.lock -> "^7.3|^8.0"
      <unknown>     -> ""

improper constraint: ^7.3|^8.0

Build Configuration

• What platform (pack, kpack, tekton buildpacks plugin, etc.) are you
  using? Please include a version.

pack-v0.17.0-linux.tgz

• What buildpacks are you using? Please include versions.

pass: paketo-buildpacks/[email protected]
pass: paketo-buildpacks/[email protected]

• What builder are you using? If custom, can you provide the output from pack inspect-builder <builder>?

# This comand runs before packing
pack config default-builder paketobuildpacks/builder:full

• Can you provide a sample app or relevant configuration (buildpack.yml,
  nginx.conf, etc.)?

How to reproduce

Use the following script.

#!/usr/bin/env bash

set -eu
set -o pipefail

pack config default-builder paketobuildpacks/builder:full

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
sudo php composer-setup.php --filename=composer
sudo chmod +x composer
sudo mv composer /usr/local/bin/composer
php -r "unlink('composer-setup.php');"

# Create a new laravel project here
composer create-project laravel/laravel laravel-base

pushd laravel-base

// ...

pack build test-laraboot-app --path . \
--buildpack paketo-buildpacks/php-dist \
--buildpack paketo-buildpacks/php-composer \
--builder paketobuildpacks/builder:full \
--clear-cache --verbose

popd

Checklist

• [ x ] I have included log output.
• [ x ] The log output includes an error message.
• [ x ] I have included steps for reproduction.

Update module from cloudfoundry -> paketo-buildpacks

The current go.mod file references a github.com/cloudfoundry repo. Now that this repo lives in the paketo-buildpacks org, we should update the module name and the internal import statements in this codebase.