aheadworks/phpdev repository overview

⁠docker-phpdev

Base image for PHP development.

Development purposes only.

This image does a number of things that are convenient locally but are unsafe for production (for example, PHP-FPM runs as root).

⁠Project structure

Templates are rendered with Jinja2⁠ (via the m4x0nus/multiplicator image in CI).

⁠Building

⁠PHP 8.x in out/ (generated)

Dockerfiles under out/ are generated automatically. Do not edit them by hand. Edit skeletons/ and config.yaml, then regenerate (see below).

⁠Adding or changing published PHP versions

1. Edit config.yaml: add or adjust entries under out: (keep versions in descending order, as noted in the file).
2. On Docker Hub, add matching tags if needed (repository builds⁠; autobuild is typically off for this flow).
3. Push to master so Bitbucket Pipelines regenerates out/, commits, and triggers your external build hook.

⁠Regenerating out/ locally

From the repository root (with config.yaml present):

docker run --rm -u "$(id -u "${USER}")":"$(id -g "${USER}")" -v "${PWD}:/data" m4x0nus/multiplicator update -d /data -c /data/config.yaml

CI runs the same updater from m4x0nus/multiplicator with python3 /app/main.py update -d ${PWD} against the repo root.

⁠Dockerfiles you may edit manually

Only legacy/ — old PHP lines that are no longer generated from out/.

⁠Building a specific image locally

Build from the directory for that tag, not the repo root (each tag has its own Dockerfile and context files).

docker build -t aheadworks/phpdev:8.2 ./out/8.2

Xdebug variants are separate generated directories (Xdebug is baked in at template time, not toggled with a build-arg):

docker build -t aheadworks/phpdev:8.2-xdebug ./out/8.2-xdebug

⁠Build arguments

These match the ARG / ENV blocks in the generated Dockerfiles (defaults shown).

XDEBUG_CLIENT_HOST is set in the image to host.docker.internal for IDE connectivity from the container.

⁠What is inside

• PHP-FPM (official php:*-fpm-alpine base)
• nginx
• crond (started by the entrypoint in serve mode)
• Composer (binary copied from official composer:2 image)
• mhsendmail
• Python 3 + Click (entrypoint)

⁠PHP extensions

• bcmath
• ftp
• gd
• intl
• mbstring
• opcache
• pcntl
• pdo_mysql
• soap
• sockets
• xsl
• xdebug (only in *-xdebug tags)
• zip

⁠Usage

Default command starts cron, nginx on port 80, and PHP-FPM (typically 9000 inside the container).

docker run -p 80:80 aheadworks/phpdev:8.2

Any other arguments are executed as a command (after the entrypoint’s host-route helper), for example:

docker run --rm aheadworks/phpdev:8.2 uname -a

⁠Xdebug on Docker Desktop (macOS / Windows)

Older Xdebug 2 “remote connect back” settings do not apply to Xdebug 3.

If the IDE does not attach, turn off client discovery so Xdebug relies on the fixed client host (host.docker.internal in the image). The xdebug ini is written to read these from the environment, so you can override at run time:

docker run -e XDEBUG_DISCOVER_CLIENT_HOST=0 -p 80:80 aheadworks/phpdev:8.2-xdebug

To bake a different default into the image, rebuild with --build-arg XDEBUG_DISCOVER_CLIENT_HOST=0.

Ensure your IDE listens on the same port as XDEBUG_CLIENT_PORT (default 9001).