bfren/php repository overview

⁠PHP

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

A small image for running PHP⁠ on the command line - scripts, Composer-style tools, scheduled jobs - with PHP 7.4 to 8.5 from Alpine's own packages.

It is Alpine⁠ with:

• the PHP command-line interpreter, and nothing else - add the extensions you need
• the official php.ini (production or development), with your own values applied on top
• the bf-php module, which Nginx + PHP⁠ also uses to manage php.ini and extensions

For websites, use Nginx + PHP⁠ instead - it adds nginx and PHP-FPM.

⁠Quickstart

Run a script in the current folder:

docker run --rm -v ./:/ws quay.io/bfren/php:php8.5 php script.php

The current folder is mounted at /ws, which is the working directory. If the first argument starts with - it is passed to php, so this is the same:

docker run --rm -v ./:/ws quay.io/bfren/php:php8.5 -f script.php

⁠Features

• 🐘 PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5 - choose with the image tag
• 📄 The official php.ini-production (or -development) file for your PHP version, downloaded from the PHP source
• ⚙️ Override any php.ini value with a small JSON file
• 🧩 Add extensions by name with bf-php ext install

⁠Tags

Images are published to Docker Hub (bfren/php) and Quay.io (quay.io/bfren/php) for linux/amd64, linux/arm/v7 and linux/arm64. Tags start with the PHP version.

Each PHP version is built on the Alpine release that packages it:

PHP 8.1 and older no longer receive security fixes, and nor do the Alpine releases they are built on - use them only for legacy code. Source: php.net⁠

⁠Configuration

⁠Volumes

⁠Environment Variables

⁠How It Works

⁠Starting

The entrypoint, /init, runs before every command:

1. It saves the container's environment, so bf scripts can read it.
2. It runs bf-php init, which sets up php.ini (below).
3. It changes to /ws and runs your command. If the first argument starts with -, it runs php with your arguments.

There is no default command - docker run bfren/php on its own does nothing.

⁠php.ini

When the image is built, the official php.ini-production file is downloaded from the PHP source on GitHub, from the branch for the installed version (e.g. PHP-8.5). At every start:

• if BF_PHP_ENV asks for a different file (development), that file is downloaded instead - so the container needs internet access the first time
• if /php-ini.json exists, each of its values is set in php.ini, replacing the existing line or adding a new one

For example, to show errors while developing:

{
    "display_errors": "On",
    "display_startup_errors": "On"
}

docker run --rm -v ./:/ws -v ./php-ini.json:/php-ini.json:ro -e BF_PHP_ENV=development quay.io/bfren/php:php8.5 php script.php

⁠Extensions

Only the PHP interpreter is installed. Add extensions in your own image - they are Alpine packages, named <prefix>-<extension> (e.g. php85-mbstring), and bf-php ext install adds the prefix for you:

# overlay/tmp/install
#!/usr/bin/nu

use bf
use bf-php

def main [] {
    bf-php ext install [mbstring pdo_mysql]
}

bf-php ext install_from_file installs from a list in /tmp/PHP_EXT, one per line: lines starting - get the prefix (-mbstring becomes php85-mbstring), other lines are installed as written. Find package names at pkgs.alpinelinux.org⁠ - change php85 to your version's prefix.

⁠The bf-php module

⁠Building on this image

FROM quay.io/bfren/php:php8.5-3.1

COPY ./overlay /
RUN bf-install

Put your installation steps (e.g. extensions) in overlay/tmp/install. See Alpine⁠ for everything else.

⁠Testing

./test.nu        # builds the PHP 8.5 image and runs /test
./test.nu 8.2    # the same for PHP 8.2
./test.nu --all  # every version, in parallel
./run.sh         # builds the PHP 8.5 image in development mode, with php-ini-sample.json applied, and opens a shell

/test runs this image's tests alongside Alpine's, and fails if tests don't execute. They check that PHP runs and matches the version in the build log, that php links to the versioned executable and loads the downloaded php.ini, how php.ini values are replaced or added, and how extension names become package names.

⁠Troubleshooting

⁠Nothing happens when I run the image

There is no default command. Give it one, e.g. php script.php or php -v.

⁠Setting BF_PHP_EXT with docker run does nothing

In this image extensions are only installed when the image is built. Install them in your own image (see Extensions⁠). Nginx + PHP⁠ is different - it installs BF_PHP_EXT at every start.

⁠"Call to undefined function"

The function's extension isn't installed - check pkgs.alpinelinux.org⁠ for the package and add it.

⁠FAQs

⁠Why Alpine's PHP packages and not the official PHP image?

They are small, receive Alpine's security fixes, and install extensions as packages in seconds - no compiling. The catch is that each PHP version is tied to the Alpine release that packages it.

⁠Why are some versions on old Alpine releases?

Alpine only packages a few PHP versions in each release, so older PHP versions come from the last Alpine release that had them.

⁠Licence

⁠Copyright