docker-php-fpm/php_tools/README.md

PHP Tools: Overview | PHP Tools: options.yml | PHP Tools: install.yml

---

Contributor Documentation: PHP Tools

PHP Tool definitions

This document describes how to create new or alter existing PHP tools.

All PHP tools (for all PHP versions and both for amd64 and arm64 platforms) are defined in the php_tools/ directory in their corresponding sub directory. Tools defined in there will be built for the work flavour.

Directory Structure:

php_tools/
└── <php-tool>/
    ├── install.yml
    ├── options.yml
    └── README.md

Requirements

In order to create new or altere existing PHP tools you need to have the following tools installed locally:

• Python3
• Python PyYAML module
• Docker
• The make command

Additionally you should have a brief understanding about what flavours exist and how they derive from each other: Documentation: Flavours.

How to add PHP tools?

Simply add your new tool definitions into php_tools/ as shown in the above directory structure.

You can either look at existing tools to find out what needs to be added to install.yml and options.yml or you check out the documentation for that:

• See PHP-TOOL-install.yml.md how to alter the install.yml file.
• See PHP-TOOL-options.yml.md how to alter the options.yml file.

Below is a simple example of how the yq tool was created:

# Enter the php_tools directory
cd php_tools/

# Create the yq directory
mkdir yq

# Create necessary empty files
touch yq/install.yml
touch yq/options.yml

Now let's edit options.yml:

---
name: yq       # The name must match the directory name
exclude: []    # Any PHP versions to exclude?

depends: [jq]  # The jq tool must be installed (yq depends on it)

Now let's edit the install.yml:

---
check: yq --version 2>&1 | grep -E '[0-9][.0-9]+' || (yq --version; false)

all:
  type: pip
  version:
  build_dep: []
  run_dep: []
  pre:
  post:

How to generate the Dockerfiles?

Dockerfiles are generated for all PHP versions with a single make command. If you do not specify any arguments, then all PHP tools found in the php_tools/ directory are being added to the Dockerfiles.

You can however also generate Dockerfiles only containing the tool that you have created/altered. This makes the docker build process much faster and you can troubleshoot potential errors quicker.

Generate Dockerfiles for all PHP tools

Inside the root of this git repository execute the following:

# Generate Dockerfiles with all available PHP tools found in php_tools/ dir
make gen-dockerfiles

Generate Dockerfiles for a single PHP tool

Inside the root of this git repository execute the following:

# Generate Dockerfiles with only yq tool
make gen-dockerfiles PHP_TOOLS="yq"

🛈 Note: This will also add any tools that yq depends on (specified via depends: in options.yml)

You can also exlcude any dependent tools by specifying the -i flag.

# Generate Dockerfiles with only yq tool and no dependent tools
make gen-dockerfiles PHP_TOOLS="-i yq"

⚠ Warning: The -i option might break your build.

Generate Dockerfiles for multiple PHP tools

Inside the root of this git repository execute the following:

# Generate Dockerfiles with only yq and zsh tool
make gen-dockerfiles PHP_TOOLS="yq zsh"

🛈 Note: This will also add any tools that yq and zsh depends on (specified via depends: in options.yml)

You can also exlcude any dependent tools by specifying the -i flag.

# Generate Dockerfiles with only yq and zsh tool and no dependent tools
make gen-dockerfiles PHP_TOOLS="-i yq zsh"

How to build the Dockerfiles?

Once you have generated the Dockerfiles, pick a PHP version and an architecture (linux/am64 or linux/arm64) and then build it via make.

🛈 Note 1: PHP tools are generated into Dockerfiles of the work flavour, so you will have to use STAGE=work to build this flavour.
🛈 Note 2: The work flavour depends on the slim flavour, so you need to ensure to either pull this Docker image or build it yourself.

The following example will show the build for:

• PHP version: 8.1
• Architecture: linux/amd64

Ensure to have slim flavour

Either build it yourself for the specific PHP version and architecture.

make build STAGE=slim VERSION=8.1 ARCH=linux/amd64

Or pull it from Dockerhub

make docker-pull-base-image STAGE=work VERSION=8.1 ARCH=linux/amd64

Build the work flavour

This flavour will include the PHP tools you have generated above.

make build STAGE=work VERSION=8.1 ARCH=linux/amd64