Product Docs
Open Source
Education
The PHP images maintained by Chainguard are a mix of development and production distroless images that are suitable for building and running PHP workloads.
Because PHP applications typically require the installation of third-party dependencies via Composer, using a pure distroless image for building your application would not work. In cases like this, you’ll need to implement a multi-stage Docker build that uses one of the -dev images to set up the application.
-dev
In this guide, we’ll set up a distroless container image based on Wolfi as a runtime to execute a command-line PHP application.
We’ll start by creating a basic command-line PHP application to serve as a demo. This app will generate random names based on a list of nouns and adjectives. To exemplify usage with Composer, the app will have a single dependency on minicli, a minimalist CLI framework for PHP.
First, create a directory for your app. In this guide we’ll use wolfi-php:
wolfi-php
mkdir ~/wolfi-php && cd ~/wolfi-php
If you have a local PHP development environment with Composer, you can run the following command to download the single dependency of this app.
composer require minicli/minicli
If you don’t have a local PHP development environment, you can use the php:latest-dev image variant with a volume in order to install application dependencies with Composer:
php:latest-dev
docker run --rm -v ${PWD}:/work --entrypoint composer \ cgr.dev/chainguard/php:latest-dev \ require minicli/minicli --working-dir=/work
If you used the Docker method, make sure permissions are set correctly on the generated files.
On Linux systems run the following:
sudo chown -R ${USER}.${USER} .
On macOS systems, run this:
sudo chown -R ${USER} .
Create a new file to serve as the application entry point. We’ll call it namegen:
namegen
touch namegen
Next, open the file in your code editor of choice, for example with nano:
nano
nano namegen
The following PHP script defines a minimalist CLI app with a single command called get. It returns a random name based on a list of nouns and a list of adjectives.
get
#!/usr/bin/php <?php require __DIR__ . '/vendor/autoload.php'; use Minicli\App; $app = new App(); $app->registerCommand('get', function () use ($app) { $animals = [ 'turtle', 'seagull', 'octopus', 'shark', 'whale', 'dolphin', 'walrus', 'penguin', 'seahorse']; $adjectives = [ 'ludicrous', 'mischievous', 'graceful', 'fortuitous', 'charming', 'ravishing', 'gregarious']; $app->getPrinter()->info($adjectives[array_rand($adjectives)] . '-' . $animals[array_rand($animals)]); }); $app->runCommand($argv);
Copy this content to your namegen script, save and close the file. Next, make the script executable with:
chmod +x namegen
You can now execute the app to test it out. If you have php locally, run:
php
php namegen get
If you’re using the Docker setup, run:
docker run --rm -v ${PWD}:/work \ cgr.dev/chainguard/php:latest \ /work/namegen get
The command should output a random name combination:
ludicrous-walrus
The demo application is now ready. In the next step, you’ll create a Dockerfile to run your app.
To make sure our final image is distroless while still being able to install dependencies with Composer, our build will consist of two stages: first, we’ll build the application using the dev image variant, a Wolfi-based image that includes Composer and other useful tools for development. Then, we’ll create a separate stage for the final image. The resulting image will be based on the distroless PHP Wolfi image, which means it doesn’t come with Composer or even a shell.
dev
Create a Dockerfile with:
touch Dockerfile
Then open this file in your code editor of choice, for example nano:
nano Dockerfile
The following Dockerfile will:
builder
/app
composer install
php:latest
Copy this content to your own Dockerfile:
Dockerfile
FROM cgr.dev/chainguard/php:latest-dev AS builder USER root COPY ../reference/php /app RUN chown -R php /app USER php RUN cd /app && \ composer install --no-progress --no-dev --prefer-dist FROM cgr.dev/chainguard/php:latest COPY --from=builder /app /app ENTRYPOINT [ "php", "/app/namegen" ]
Save the file when you’re finished.
You can now build the image with:
docker build . -t php-namegen
Once the build is finished, run the image with:
docker run --rm php-namegen get
And you should get output similar to what you got before, with a random name combination.
fortuitous-octopus
If you inspect the image with a docker image inspect php-namegen, you’ll notice that it has only two layers, thanks to the use of a multi-staging Docker build.
docker image inspect php-namegen
... "RootFS": { "Type": "layers", "Layers": [ "sha256:23a50695d43b8aea7720c05bff1bdbfbcb45d0b0c7e7387f55d82110084002eb", "sha256:9b900cbd280a3d510588c3b14bc937718ccee43a10b8b7b1756438b030bc3e15" ] }, "Metadata": { "LastTagTime": "2023-01-10T19:02:13.062958609+01:00" } } ]
In such cases, the last FROM section from the Dockerfile is the one that composes the final image. That’s why in our case it only adds one layer on top of the base php:latest image, containing the COPY command we use to copy the application from the build stage to the final image.
FROM
COPY
It’s worth highlighting that nothing is carried from one stage to the other unless you copy it. That facilitates creating a slim final image with only what’s necessary to execute the application.
If your project requires a more specific set of packages that aren't included within the general-purpose PHP Chainguard Image, you'll first need to check if the package you want is already available on the wolfi-os repository.
If the package is available, you can use the wolfi-base image in a Dockerfile and install what you need with apk, then use the resulting image as base for your app. Check the "Using the wolfi-base Image" section of our images quickstart guide for more information.
apk
If the packages you need are not available, you can build your own apks using melange. Please refer to this guide for more information.