paketo-buildpacks / php-start

PHP Start Command CNB

PHP Start Cloud Native Buildpack

gcr.io/paketo-buildpacks/php-start

A Cloud Native Buildpack for running HTTPD, Nginx, and FPM start commands for PHP apps.

Behavior

This buildpack will always participate if its requirements are met. In the HTTPD server case requires php, php-fpm optionally, httpd, and php-httpd-config. In the Nginx case, it will require nginx and php-nginx-config instead of httpd and php-httpd-config.

In either the HTTPD server or Nginx case, this buildpack will require composer-packages when a composer.json file is available.

When this buildpack runs, the PHP_HTTPD_PATH OR the PHP_NGINX_PATH environment variable must be set by another buildpack in conjunction with PHP_FPM_PATH. This is because both the HTTPD and Nginx web servers will require FPM to serve PHP apps. The build will fail if both PHP_HTTPD_PATH and PHP_NGINX_PATH are set or both unset, as well as if the PHP_FPM_PATH environment variable is not set. These requirements will be met when used in conjunction with the other buildpacks in the Paketo PHP language family. Because of this, the usage of this buildpack is fairly tightly coupled to other buildpacks in the PHP language family.

Requirement	Build	Launch
php	x
composer-packages		x
php-fpm	x	x
httpd or nginx	x
httpd-config or nginx-config	x	x

It will set the default start command to something that looks like:

procmgr-binary /layers/paketo-buildpacks_php-start/php-start/procs.yml

The procmgr-binary is a process manager that will run multiple start commands on the container. This is done to allow for FPM to run on the container alongside the web server. The procs.yml file it runs with contains the commands and arguments for both php-fpm and the web-server.

When the buildpack runs, you will see in the logs what processes are added to procs.yml.

Live Reload

Both httpd and nginx automatically reload changed files, so applications built by this buildpack implicitly support live reloading of served files.

This buildpack adds explicit live reload support for httpd and nginx configuration files at the following locations:

• http: <app-directory>/.httpd.conf.d/
• nginx: <app-directory>/.nginx.conf.d/

See the following integration test files for examples of both application code live reload and configuration live reload.

• integration/httpd_reload_test.go
• integration/nginx_reload_test.go

Integration

This CNB writes a start command, so there's currently no scenario we can imagine that you would need to require it as dependency.

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh --version <version-number>

This will create a buildpackage.cnb file under the build directory which you can use to build your app as follows:

pack build <app-name> \
  --path <path-to-app> \
  --buildpack build/buildpackage.cnb

Run Tests

To run all unit tests, run:

./scripts/unit.sh

To run all integration tests, run:

/scripts/integration.sh

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-start's Issues

Support Composer applications by requiring `composer-packages` when necessary

Given I'm a developer writing a PHP Composer app
When I use Composer to download my application's dependencies and have a composer.json file
Then I want this buildpack (php-start) to require composer-packages so that the composer-install buildpack will provide my application's dependencies

Detection of the Composer use case happens when either of these cases is true:

• composer.json exists at the root level of the working directory
• the COMPOSER environment variable points to an existing file underneath the working directory (this overrides the default composer.json file)

This buildpack's "web" process overrides the one in Procfile

If I add a Procfile at the root of my app with the following:

web: echo "hello"

Then I'd expect that to take priority over the "web" process added by the php-start buildpack. However, when I run pack build, the paketo-buildpacks/procfile buildpack runs before the paketo-buildpacks/php-start buildpack, and so the resulting image's web process is the one set by php-start rather the one I specified in my Procfile.

Is my expectation correct, or is it by design that php-start override procfile?

In the meantime, I can work around this by using a different name than "web" in my Procfile and then making that other name the default process. Or, is there a better workaround available: for example, is there something I can do to change the order in which build packs run so that paketo-buildpacks/procfile runs after paketo-buildpacks/php-start?

Demonstrate live reload without watchexec

Does this implement paketo-buildpacks/php#542 ?

Restructure buildpack: PHP Start for Nginx

BLOCKED on paketo-buildpacks/php-nginx#2

Context

PHP RFC 0003 is an addendum to PHP Restructure RFC 0001. The RFC outlines creating a PHP Start buildpack for managing the task of running start commands for HTTPD, Nginx, and FPM.

Issue

This is to add the new PHP start buildpack base implementation with support for the Nginx + FPM start command use case. Separate issues will be filed to address HTTPD + FPM, HTTPD only, and Nginx only.

Logic to support running two start commands already lives in the PHP Web buildpack procmgr, and a similar implementation can be used in this buildpack.

• API: the buildpack should require: php, php-fpm (optional), and nginx-config at build, and
  php-fpm (optional), nginx, and nginx-config and launch.
• Buildpack API Version: This buildpack should be written using Buildpack API 0.7
• https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.7
• README: Make sure a README is added that conveys context about the buildpack in a manner consistent with other Paketo buildpacks.

Acceptance

I can successfully build an PHP app with a Nginx server using the Paketo PHP Dist Buildpack, Paketo PHP FPM buildpack, the Paketo PHP Nginx buildpack, and this new buildpack, specifying an intent to use Nginx as the server of choice. I should be able to ping the app successfully, and container logs show that FPM is running inside the container as well.

Failure: Approve bot PR workflow

Approve bot PR workflow failed.

Restructure buildpack: PHP Start for HTTPD

Context

PHP RFC 0003 is an addendum to PHP Restructure RFC 0001. The RFC outlines creating a PHP Start buildpack for managing the task of running start commands for HTTPD, Nginx, and FPM.

Issue

This is to add the new PHP start buildpack base implementation with support for the HTTPD + FPM start command use case. Separate issues will be filed to address Nginx + FPM, HTTPD only, and Nginx only.

Logic to support running two start commands already lives in the PHP Web buildpack procmgr, and a similar implementation can be used in this buildpack.

• API: the buildpack should require: php, php-fpm (optional), and httpd-config at build, and
  php-fpm (optional), httpd, and httpd-config and launch.
• Buildpack API Version: This buildpack should be written using Buildpack API 0.7
• README: Make sure a README is added that conveys context about the buildpack in a manner consistent with other Paketo buildpacks.
• Use direct process types where applicable

Acceptance

I can successfully build an PHP app with a HTTPD server using the Paketo PHP Dist Buildpack, Paketo PHP FPM buildpack, the Paketo PHP HTTPD buildpack, and this new buildpack, specifying an intent to use HTTPD as the server of choice. I should be able to ping the app successfully, and container logs show that FPM is running inside the container as well.

Failure: Push Buildpackage workflow

Push Buildpackage workflow failed.

Restructure buildpack: PHP Start without FPM

BLOCKED on paketo-buildpacks/php-fpm#8

Context

PHP RFC 0003 is an addendum to PHP Restructure RFC 0001. The RFC outlines creating a PHP Start buildpack for managing the task of running start commands for HTTPD, Nginx, and FPM.

Issue

This is to add the new PHP start buildpack base implementation with support for the Nginx and HTTPD as standalone servers, without FPM in the same container. Based on the outcome from paketo-buildpacks/php-fpm#8, this buildpack will need to implement a solution for discovering that FPM should run separately, and run HTTPD or Nginx alone in a container.

Failure: Create Draft Release workflow

Create Draft Release workflow failed.