### Set up Complete Web Stack with Nginx and PHP-FPM using Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example demonstrates setting up a complete web stack by running PHP-FPM and Nginx containers and linking them. It involves creating a project directory, starting the PHP-FPM container with mounted project files, and then starting the Nginx container, linking it to PHP-FPM. The setup is tested using `curl`.

```bash
# Create project directory
mkdir -p ~/my-project
echo "<?php phpinfo();" > ~/my-project/index.php

# Start PHP-FPM container
docker run -d -it \
    -v ~/my-project:/var/www/default/htdocs \
    -e NEW_UID=$(id -u) \
    -e NEW_GID=$(id -g) \
    --name php \
    devilbox/php-fpm:8.2-prod

# Start Nginx and link with PHP-FPM
docker run -d -it \
    -p 80:80 \
    -v ~/my-project:/var/www/default/htdocs \
    -e PHP_FPM_ENABLE=1 \
    -e PHP_FPM_SERVER_ADDR=php \
    -e PHP_FPM_SERVER_PORT=9000 \
    --link php \
    --name nginx \
    devilbox/nginx-mainline

# Test the setup
curl http://localhost/index.php
```

--------------------------------

### Execute Custom Startup Scripts in Docker Container

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example demonstrates how to run custom scripts during the startup of a devilbox/php-fpm container. It involves creating a `startup` directory on the host, placing executable shell scripts within it, and then mounting this directory to `/startup.1.d` inside the container. The scripts will be executed automatically upon container start.

```bash
# Create startup scripts directory
mkdir -p startup

# Script to install additional packages
cat > startup/install-packages.sh << 'EOF'
#!/bin/bash
apt-get update && apt-get install -y imagemagick
EOF
chmod +x startup/install-packages.sh

# Script to configure application
cat > startup/configure-app.sh << 'EOF'
#!/bin/bash
echo "Setting up application..."
cp /var/www/default/htdocs/.env.example /var/www/default/htdocs/.env
EOF
chmod +x startup/configure-app.sh

# Run container with startup scripts
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v $(pwd)/startup:/startup.1.d \
    devilbox/php-fpm:8.2-prod
```

--------------------------------

### PHP Tool Installation Configuration (YAML)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

An example `install.yml` file for a PHP tool. It includes a check command to verify the tool's installation and specifies build and runtime dependencies.

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

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

--------------------------------

### NPM Package Installation Configuration (install.yml)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

This YAML example shows how to configure the installation of NPM packages for PHP Tools. The 'all' block specifies the 'pm2' package with its corresponding binary path. The 'version' field is left empty, indicating the latest version will be installed.

```yaml
all:
  type: npm
  package: pm2
  binary: pm2
  version:

```

--------------------------------

### Perform MySQL Database Backups using mysqldump-secure with Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example shows how to perform MySQL database backups using the `mysqldump-secure` tool within a devilbox/php-fpm:8.2-work container. It involves starting the container with necessary MySQL credentials and linking it to a MySQL server, then executing the backup command. Backups are stored in a host-mounted directory.

```bash
# Start work container with MySQL backup credentials
docker run -d -it \
    -e MYSQL_BACKUP_USER=root \
    -e MYSQL_BACKUP_PASS=secretpassword \
    -e MYSQL_BACKUP_HOST=mysql-server \
    -v ~/backups:/shared/backups \
    --name php \
    --link mysql-server \
    devilbox/php-fpm:8.2-work

# Execute database backup
docker exec -it php mysqldump-secure

# Backups are stored in ~/backups on host
ls -la ~/backups/
```

--------------------------------

### Integrate Webserver with PHP-FPM

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example shows how to set up a PHP-FPM container and a webserver (Nginx) container to work together. It involves mounting the web root directory into both containers and configuring the webserver to forward PHP requests to the PHP-FPM service.

```shell
# Start PHP-FPM container
docker run -d -it \
    -v ~/my-host-www:/var/www/default/htdocs \
    --name php \
    devilbox/php-fpm:7.2-prod

# Start webserver and link with PHP-FPM
docker run -d -it \
    -p 80:80 \
    -v ~/my-host-www:/var/www/default/htdocs \
    -e PHP_FPM_ENABLE=1 \
    -e PHP_FPM_SERVER_ADDR=php \
    -e PHP_FPM_SERVER_PORT=9000 \
    --link php \
    devilbox/nginx-mainline
```

--------------------------------

### Configure Debug Logging Verbosity with Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example shows how to control the debug logging level during the startup of a devilbox/php-fpm container using the DEBUG_ENTRYPOINT environment variable. Setting it to 2 provides maximum verbosity, showing all executed commands. The example also demonstrates redirecting PHP logs to files instead of Docker logs by setting DOCKER_LOGS=0 and mounting a volume for logs.

```bash
# Maximum verbosity during startup (shows all commands)
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e DEBUG_ENTRYPOINT=2 \
    devilbox/php-fpm:8.2-prod

# Log to files instead of docker logs
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e DOCKER_LOGS=0 \
    -v /tmp/php-logs:/var/log/php \
    devilbox/php-fpm:8.2-prod

# View PHP logs
tail -f /tmp/php-logs/php-fpm.access.log
tail -f /tmp/php-logs/php-fpm.error.log
```

--------------------------------

### Launch Postfix for Mail Catching

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example configures the PHP-FPM container to use Postfix for catching outgoing emails. When `ENABLE_MAIL=2` is set, all emails sent by PHP applications are captured locally. Mounting the mail directory allows external tools to access these caught emails.

```shell
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v /tmp/mail:/var/mail \
    -e ENABLE_MAIL=2 \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### Single-line Shell Code Example in Devilbox

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

Demonstrates defining shell code on a single line for keys that support it, such as the `pre` directive.

```yaml
all:
  pre: VERSION="$( curl http://url | grep -Eo '[0-9.]+' )"

```

--------------------------------

### Create MySQL Backups with PHP-FPM Work Image

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example demonstrates how to create MySQL backups using the `mysqldump-secure` command within a PHP-FPM 'work' Docker image. It involves setting up environment variables for MySQL connection details and mounting a volume for storing the backups.

```shell
# Start container
docker run -d -it \
    -e MYSQL_BACKUP_USER=root \
    -e MYSQL_BACKUP_PASS=somepass \
    -e MYSQL_BACKUP_HOST=mysql \
    -v ~/backups:/shared/backups \
    --name php \
    devilbox/php-fpm:7.2-work

# Run database dump
docker exec -it php mysqldump-secure
```

--------------------------------

### Forward MySQL and Redis Ports to Localhost

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example demonstrates forwarding multiple ports, specifically MySQL and Redis, to the PHP-FPM container's localhost. This enables seamless connectivity from PHP applications to both database services using `127.0.0.1`.

```shell
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e FORWARD_PORTS_TO_LOCALHOST='3306:172.168.0.30:3306, 6379:redis:6379' \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### Multi-command Shell Code Example in Devilbox

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

Shows how to execute multiple shell commands sequentially using `&&` within a multi-line definition. This allows for chained operations.

```yaml
all:
  pre: |
    URL="http://url" \
    && VERSION="$( \
      curl "${URL}" \
      | grep -Eo '[0-9.]+' \
    )" \
    && echo "${VERSION}" \

```

--------------------------------

### Load Custom PHP Configuration

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example illustrates how to load custom PHP configuration files (e.g., `xdebug.ini`) into the PHP-FPM container. By mounting a local directory containing the `.ini` files to `/etc/php-custom.d` within the container, you can override or extend the default PHP settings.

```shell
# Create config directory to be mounted with dummy configuration
mkdir config
# Xdebug 2
echo "xdebug.enable = 1" > config/xdebug.ini
# Xdebug 3
echo "xdebug.mode = debug" > config/xdebug.ini

# Run container and mount it
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v config:/etc/php-custom.d \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### YAML Configuration for PHP Tool Installation (install.yml)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

This YAML snippet demonstrates the structure for defining tool installations in Devilbox's PHP Tools. It includes top-level definitions for a check command and default settings ('all'), as well as version-specific overrides (e.g., '5.2'). The 'all' block sets default installation parameters, while specific versions can overwrite these.

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

# Default for all PHP version if no overwrite exists
all:
  type: pip
  version:
  build_dep: []
  run_dep: []
  pre:
  post:


# PHP 5.2 is overwriting the version of yq to install
5.2:
  type: pip
  version: 0.1.0

```

--------------------------------

### Custom Module Installation Command (YAML)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-install.yml.md

Defines a custom command to install and enable a PHP module. This example shows a multi-line shell script for downloading, extracting, configuring, and installing a module.

```yaml
all:
  type: custom
  command: |
    wget http://url/file.tar.gz \
	&& tar xvfz file.tar.gz \
	&& cd file \
	&& phpize \
	&& ./configure \
	&& make \
	&& make install \

```

--------------------------------

### APT Package Installation Configuration (install.yml)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

This YAML configuration illustrates how to define the installation of Debian apt packages for PHP Tools. It shows the 'all' block for a general package ('netcat') and a version-specific override for PHP 5.3 to install 'netcat.traditional'.

```yaml
all:
  type: apt
  package: netcat

5.3:
  type: apt
  package: netcat.traditional

```

--------------------------------

### PIP Package Installation with Post-Install Script (install.yml)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

This YAML configuration demonstrates installing a Python package using pip for PHP Tools. The 'all' block specifies the type as 'pip' and includes a multi-line 'post-install' script to create a symbolic link. The 'version', 'build_dep', and 'run_dep' fields are shown as empty or default.

```yaml
all:
  type: pip
  version:
  build_dep: []
  run_dep: []
  pre:
  post: |
    ln -s pwncat /usr/local/bin/netcat \

```

--------------------------------

### Multi-line Shell Code Example in Devilbox

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

Illustrates defining shell code across multiple lines using the `|` indicator for readability. Each line, including the last, requires a trailing backslash.

```yaml
all:
  pre: |
    VERSION="$( \
      curl http://url \
      | grep -Eo '[0-9.]+' \
    )" \

```

--------------------------------

### PHP Tool Options Configuration (YAML)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

An example `options.yml` file for a PHP tool. It specifies the tool's name, any PHP versions to exclude, and its dependencies (e.g., 'jq' for 'yq').

```yaml
---
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)
```

--------------------------------

### Build Docker Image for a Specific PHP Version and Architecture

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_modules/README.md

Example command to build a Docker image for a specific PHP version (e.g., 8.1) and architecture (e.g., linux/amd64) using the 'mods' flavour. Ensure the 'base' flavour is available.

```bash
# Build for PHP 8.1 on linux/amd64 using the 'mods' flavour
STAGE=mods PHP_VERSION=8.1 ARCH=linux/amd64 make docker-php-fpm
```

--------------------------------

### Run PHP-FPM Container with Exposed Port

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example shows how to run the PHP-FPM Docker container and expose its default port (9000) to the host machine. This allows external applications or services to connect to the PHP-FPM process running inside the container.

```shell
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### Forward MySQL Port to Localhost

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example shows how to forward a MySQL port from a remote host or another container to the PHP-FPM container's localhost. This allows PHP applications within the container to connect to a MySQL database using `127.0.0.1` as if it were running locally.

```shell
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e FORWARD_PORTS_TO_LOCALHOST='3306:172.168.0.30:3306' \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### Define Build Dependencies for PHP Modules

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-options.yml.md

Lists other PHP modules that must be built and installed before the current module can be built. The module generator ensures these dependencies are met in the correct order. The example shows dependencies on 'igbinary' and 'msgpack'.

```yaml
depends_build:
  - igbinary
  - msgpack
```

--------------------------------

### Composer Package Installation Configuration (install.yml)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

This YAML snippet demonstrates configuring Composer package installations for PHP Tools. It includes an 'all' block for installing 'laravel/installer' with composer version 2 and a specific binary path. A version-specific block for PHP 7.1 shows how to set a package version and binary.

```yaml
all:
  type: composer
  composer: 2
  package: laravel/installer
  binary: bin/laravel

7.1:
  type: composer
  version: 2.3.0
  binary: laravel

```

--------------------------------

### Install Custom Command in Devilbox

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

Installs a custom tool using a specified command. All installed data must be placed in `/usr/local/bin`. Supports shell code for the command and pre/post-installation steps.

```yaml
all:
  type: custom
  command: curl -sS -k -L --fail -L "${PHP_CS_FIXER_URL}" -o /usr/local/bin/php-cs-fixer
  pre: PHP_CS_FIXER_URL="https://cs.symfony.com/download/php-cs-fixer-v3.phar"
  post: chmod +x /usr/local/bin/php-cs-fixer

7.3:
  type: custom
  pre: PHP_CS_FIXER_URL="https://cs.symfony.com/download/php-cs-fixer-v2.phar"

```

--------------------------------

### Add Custom Supervisord Programs using Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example illustrates how to add custom programs to supervisord within a devilbox/php-fpm container. It involves creating a supervisor configuration file (e.g., for a Laravel queue worker) and mounting it to `/etc/supervisor/custom.d` in the container. This allows running additional services alongside PHP-FPM.

```bash
# Create supervisor config for a queue worker
mkdir -p supervisor

cat > supervisor/laravel-worker.conf << 'EOF'
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/default/htdocs/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/php/worker.log
EOF

# Run with custom supervisor config
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v ~/my-laravel-project:/var/www/default/htdocs \
    -v $(pwd)/supervisor:/etc/supervisor/custom.d \
    devilbox/php-fpm:8.2-prod
```

--------------------------------

### Enable Mail Catching with Postfix using Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This command configures Postfix within the devilbox/php-fpm container to intercept all outgoing emails locally for development testing. The ENABLE_MAIL=2 environment variable enables this feature, and emails are stored in a volume mounted to /var/mail. The example also shows how to read the caught emails using `docker exec`.

```bash
# Enable mail catching (all emails intercepted locally)
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v /tmp/mail:/var/mail \
    -e ENABLE_MAIL=2 \
    devilbox/php-fpm:8.2-prod

# Read caught emails
docker exec -it php cat /var/mail/devilbox
```

--------------------------------

### Shell Scripting in YAML: Single-command vs Multi-command (YAML)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-install.yml.md

Illustrates the usage of single and multiple shell commands within YAML configurations. Multiple commands must be separated by '&&'. This example shows capturing a version number and echoing it.

```yaml
all:
  pre: |
    VERSION="$( \
      curl http://url \
      | grep -Eo '[0-9.]+' \
    )" \

```

```yaml
all:
  pre: |
    URL="http://url" \
    && VERSION="$( \
      curl "${URL} \
      | grep -Eo '[0-9.]+' \
    )" \
    && echo "${VERSION}" \

```

--------------------------------

### Define Load Order (Loads Before)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-options.yml.md

Specifies PHP modules that the current module must be loaded before. This controls the sequence in which modules are loaded within the PHP Docker image. The example indicates the current module should load before 'igbinary' and 'msgpack'.

```yaml
loads_before:
  - igbinary
  - msgpack
```

--------------------------------

### Define Build Dependencies for PHP Tools in options.yml

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-options.yml.md

Lists other tools that must be present before building or installing the current tool. The tool generator ensures that all dependencies are built in the correct order. The 'depends_build' key takes a list of strings representing the names of the required tools.

```yaml
# Before installing the current tool, it will be ensured that
# jq is build and installed beforehand.
depends_build:
  - jq
```

--------------------------------

### Define Load Dependencies for PHP Modules

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-options.yml.md

Specifies PHP modules that must be loaded before the current module for it to function correctly. The PHP Docker image respects this loading order. The example indicates that 'igbinary' and 'msgpack' should be loaded first.

```yaml
depends_load:
  - igbinary
  - msgpack
```

--------------------------------

### Define PHP Tool Exclusions in options.yml

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-options.yml.md

Specifies PHP versions to exclude from building or installing a tool. This is useful for handling build errors or deprecated versions. The 'exclude' key takes a list of strings representing the PHP versions.

```yaml
# Exclude PHP 5.2 and PHP 5.3
exclude: [5.2, 5.3]
```

--------------------------------

### Add Custom Certificate Authority using Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This example shows how to add custom CA certificates to a devilbox/php-fpm container. It involves creating a `ca-certs` directory on the host, placing your CA certificate file within it, and then mounting this directory to `/ca` inside the container. This is useful for establishing trust with internal HTTPS services.

```bash
# Create CA directory with your certificates
mkdir -p ca-certs

# Copy your organization's CA certificate
cp /path/to/company-ca.crt ca-certs/

# Run container with custom CA
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -v $(pwd)/ca-certs:/ca \
    devilbox/php-fpm:8.2-prod
```

--------------------------------

### Exclude PHP Versions for Module Build

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-options.yml.md

Specifies PHP versions for which a particular PHP module should not be built or installed. This is useful for avoiding build errors or handling deprecated versions. The example shows how to exclude PHP 5.2 and 5.3.

```yaml
exclude:
  - 5.2
  - 5.3
```

--------------------------------

### Create PHP Tool Directory and Files (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

Demonstrates the bash commands to create a new directory for a PHP tool (e.g., 'yq') within the `php_tools/` directory and create the necessary `install.yml` and `options.yml` files.

```bash
# 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
```

--------------------------------

### Build Docker Image for a Specific PHP Version and Architecture (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

Demonstrates how to build a Docker image for a specific PHP version (e.g., 8.1) and architecture (e.g., linux/amd64) using the `make build` command with `STAGE=work`. It also shows how to ensure the 'slim' flavour is available.

```bash
# 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
```

--------------------------------

### Install Rubygem Package with Version in Devilbox

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-TOOL-install.yml.md

Specifies a Rubygem package and optionally its version to be installed. Supports shell code for the version definition.

```yaml
all:
  type: rubygem
  package: mdl
  build_dep: [ruby-dev]
  run_dep: [ruby]

7.2:
  type: rubygem
  version: 0.11.0
  pre: |
    gem install chef-utils -v 16.6.14 \

```

--------------------------------

### Enable PHP Modules (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/docker-env-variables.md

Explicitly enables specified PHP modules during container startup. Modules are provided as a comma-separated string. Refer to the PHP modules documentation for available options.

```bash
ENABLE_MODULES=swoole
```

```bash
ENABLE_MODULES=swoole,psr,phalcon
```

--------------------------------

### Build PHP 8.1 Image for arm64

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This command builds a PHP 8.1 Docker image for the arm64 architecture with specified extensions. It utilizes the 'make' utility and requires setting the STAGE, VERSION, and ARCH variables.

```makefile
make build STAGE=mods VERSION=8.1 ARCH=linux/arm64
```

--------------------------------

### Configure PHP-FPM Timezone

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This example demonstrates how to set the timezone for the PHP-FPM container. By using the `TIMEZONE` environment variable, you can ensure that all PHP scripts running within the container adhere to a specific timezone, which is crucial for accurate date and time handling.

```shell
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e TIMEZONE=Europe/Berlin \
    devilbox/php-fpm:7.2-prod
```

--------------------------------

### Declare Conflicting PHP Modules

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-options.yml.md

Lists PHP modules that, if loaded concurrently, would cause the current module to malfunction. This helps prevent compatibility issues. The example marks 'igbinary' and 'msgpack' as incompatible.

```yaml
conflicts_load:
  - igbinary
  - msgpack
```

--------------------------------

### PHP-FPM Image Flavors Overview

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This diagram illustrates the inheritance structure of the Devilbox PHP-FPM Docker images. It shows how different flavors like 'slim' and 'work' are built upon base images, incorporating specific modules and configurations for production or development environments.

```shell
        [PHP]            # Base FROM image (Official PHP-FPM image)
          ^              #
          |              #
          |              #
        [base]           # Streamlined base images with host user mapping
          ^              # environment variables and custom configs.
          |              #
          |              #
        [mods]           # Installs additional PHP modules
          ^              # via pecl, git and other means
          |              #
          |              #
        [prod]           # Devilbox flavour for production
          ^              # (locales, postifx, socat and injectables)
          |              # (custom *.ini files)
          |              #
        [slim]           # Devilbox flavour with only required
          ^              # cli tools to have a functional intranet.
          |              #
          |              #
        [work]           # Devilbox flavour for local development
                         # (includes backup and development tools)
                         # (sudo, custom bash and tool configs)
```

--------------------------------

### Create and Configure a New PHP Module (xls)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_modules/README.md

Demonstrates the steps to create a new PHP module named 'xls'. This includes creating the module directory, empty configuration files, and defining build dependencies and runtime requirements in `options.yml` and `install.yml`.

```bash
# Enter the php_modules directory
cd php_modules/

# Create the xls directory
mkdir xls

# Create necessary empty files
touch xls/install.yml
touch xls/options.yml
```

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

depends_build: [libxml]  # The libxml module must be built before xls
```

```yaml
---
all:
  type: builtin
  build_dep: [libxslt-dev]  # This Debian package is required to build xls
  run_rep: [libxslt1.1]     # This Debian package is required during run-time
```

--------------------------------

### Generate Dockerfiles for All PHP Tools (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

A `make` command to generate Dockerfiles for all PHP tools defined in the `php_tools/` directory. This command should be executed from the root of the git repository.

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

--------------------------------

### Generate Dockerfiles for a Single PHP Tool (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

A `make` command to generate Dockerfiles containing only a specific PHP tool (e.g., 'yq'). This is useful for faster builds and quicker troubleshooting. It can also include dependencies.

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

--------------------------------

### Shell Scripting in YAML: Single-line vs Multi-line (YAML)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/contributor/PHP-EXT-install.yml.md

Demonstrates how shell commands can be written either as a single line or a multi-line definition within YAML configurations. Multi-line definitions require a trailing backslash '\' on each line.

```yaml
all:
  pre: VERSION="$( curl http://url | grep -Eo '[0-9.]+' )"

```

```yaml
all:
  pre: |
    VERSION="$( \
      curl http://url \
      | grep -Eo '[0-9.]+' \
    )" \

```

--------------------------------

### Generate Dockerfiles for Multiple PHP Tools (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

A `make` command to generate Dockerfiles containing multiple specified PHP tools (e.g., 'yq' and 'zsh'). This command also includes their dependencies by default.

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

--------------------------------

### Forward Multiple Services (MySQL and Redis) using Docker

Source: https://context7.com/devilbox/docker-php-fpm/llms.txt

This command forwards multiple services, specifically MySQL (3306) and Redis (6379), from external hosts to the local machine. It demonstrates how to specify multiple port mappings within the FORWARD_PORTS_TO_LOCALHOST environment variable, separated by commas. This allows simultaneous access to different services.

```bash
docker run -d -it \
    -p 127.0.0.1:9000:9000 \
    -e FORWARD_PORTS_TO_LOCALHOST='3306:mysql-server:3306, 6379:redis-server:6379' \
    devilbox/php-fpm:8.2-prod
```

--------------------------------

### Generate Dockerfiles for Multiple Tools Excluding Dependencies (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

A `make` command to generate Dockerfiles for multiple specified PHP tools (e.g., 'yq' and 'zsh') while excluding their dependencies. Use with caution.

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

--------------------------------

### Directory Structure for PHP Tools

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

Defines the standard directory structure for new or existing PHP tools within the `php_tools/` directory. Each tool has its own subdirectory containing `install.yml`, `options.yml`, and `README.md`.

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

--------------------------------

### Build Custom Docker PHP-FPM Images (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/abuser/README.md

These commands facilitate the building of custom Docker PHP-FPM images. They cover pulling the base image, building the 'mods' image with custom extensions, and optionally building the 'prod' and 'work' images for production or development environments, respectively. Requires specifying the architecture and PHP version.

```bash
ARCH=linux/amd64
VERSION=8.1
make docker-pull-base-image STAGE=mods VERSION=${VERSION} ARCH=${ARCH}
```

```bash
ARCH=linux/amd64
VERSION=8.1
make build STAGE=mods VERSION=${VERSION} ARCH=${ARCH}
```

```bash
# (Optional) Build the `prod` image
ARCH=linux/amd64
VERSION=8.1
make build STAGE=prod VERSION=${VERSION} ARCH=${ARCH}
```

```bash
# (Optional) Build the `work` image
ARCH=linux/amd64
VERSION=8.1
make build STAGE=work VERSION=${VERSION} ARCH=${ARCH}
```

--------------------------------

### Generate Dockerfiles Excluding Dependencies (Make)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/php_tools/README.md

A `make` command to generate Dockerfiles for a specific PHP tool (e.g., 'yq') while excluding any dependent tools. Use with caution as it might break the build.

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

--------------------------------

### Forward Remote Ports to Localhost (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/docker-env-variables.md

Forwards remote ports into the PHP-FPM container, allowing connections to `127.0.0.1` to reach remote services. The format is `<local-port>:<remote-host>:<remote-port>`. Multiple ports can be forwarded by comma-separating the strings.

```bash
FORWARD_PORTS_TO_LOCALHOST=3307:mysqlhost:3306
```

```bash
FORWARD_PORTS_TO_LOCALHOST=3307:mysqlhost:3306, 5433:pgsqlhost:5432
```

--------------------------------

### Configure Mail Handling (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/docker-env-variables.md

Controls the behavior of the Postfix mail service within the container when PHP sends emails. A value of '0' disables Postfix, '1' enables it with default settings, and '2' enables it for local delivery, intercepting all outgoing emails.

```bash
ENABLE_MAIL=0
```

```bash
ENABLE_MAIL=1
```

```bash
ENABLE_MAIL=2
```

--------------------------------

### Pull Base Docker Image for PHP Version and Architecture

Source: https://github.com/devilbox/docker-php-fpm/blob/master/README.md

This command pulls the base Docker image for a specified PHP version and architecture. It's a prerequisite for building custom images or ensuring you have the necessary base layers locally. The `VERSION`, `STAGE`, and `ARCH` parameters control which image is fetched.

```bash
make docker-pull-base-image STAGE=mods VERSION=8.1 ARCH=linux/arm64
```

--------------------------------

### Generate Dockerfiles with PHP Extensions (Bash)

Source: https://github.com/devilbox/docker-php-fpm/blob/master/doc/abuser/README.md

This command generates Dockerfiles for PHP-FPM images. It can generate Dockerfiles with all available PHP extensions or with a specified subset. Dependencies for selected extensions are automatically included unless explicitly ignored.

```bash
# Generate Dockerfiles with all available PHP extensions
make gen-dockerfiles
```

```bash
# Generate Dockerfiles for selected PHP extensions only
# Note: that also all dependent extensions will be added
make gen-dockerfiles MODS="msgpack xsl"
```

```bash
# Generate Dockerfiles for selected PHP extensions
# and ignore dependencies
make gen-dockerfiles MODS="-i msgpack xsl"
```