# PHP and Composer in container stages

Source: https://codeherder.com/docs/php-stages/

Run PHP 8.5, Composer, mago, MySQL-compatible MariaDB and Redis in a container stage. Private GitLab and Packagist packages install.

A project that builds with PHP needs more than the default stage image gives it. This page shows a recipe for PHP 8.5, Composer, the `mago` linter, a database and Redis in a stage. It also shows how Composer reaches its packages.

The recipe has three parts. A Dockerfile fragment installs PHP. An environment tool set provisions mago. A setup script starts the database and Redis. Your repo keeps its own `composer.json` and `composer.lock`.

> **Status.** Option A built and went `ready` on one device, IAP EC2, on 2026-10-23, about 2 minutes after the layer save. The hosts were `packages.sury.org:443/connect` and `getcomposer.org:443/connect`, approved for build only. A stage on that image ran PHP 8.5.11 and Composer 2.9.5. `mago` is now declared in the environment tool set rather than installed by the setup script. The historical proof below predates this provisioning change. SmartFlow EC2 is not part of this proof. Options B and C are not proven. A build rule never opens a host to a stage. A writable stage runs in strict mode and refuses the host: on IAP EC2, both `packages.sury.org` and `getcomposer.org` returned `403 not_allowlisted`. A read-only stage keeps `EGRESS_MODE`, which is open by default, so it can reach any public host. See [Isolating agents on a device](https://codeherder.com/docs/agent-isolation/). Read the build log and fix any package name that moved.

## How Composer reaches its packages

A stage never points Composer at a cache or at a mirror. Composer keeps the real addresses, so `composer.lock` is correct on every machine.

| Source | What happens |
| --- | --- |
| Packagist metadata, `repo.packagist.org` | The stage proxy answers and serves it from the device [download cache](https://codeherder.com/docs/package-downloads/). |
| Packagist archives | Packagist lists a GitHub zipball for most packages. The proxy serves a commit zipball from the cache. Every other `api.github.com` request stays refused. |
| Private GitLab Composer registry on gitlab.com | CodeHerder relays `GET` and `HEAD` reads and adds a read-only token. The token never enters the stage. |
| `packagist.org` | The strict list of allowed hosts includes it, so `composer audit` works. The cache does not store it. |

Keep the GitLab registry in `composer.json` as you wrote it:

```
{
  "repositories": [
    { "type": "composer", "url": "https://gitlab.com/api/v4/group/<group-id>/-/packages/composer/" }
  ]
}
```

The `<group-id>` is the numeric group id. A group path such as `acme/tools` is refused.

**Private GitHub packages.** The zipball cache cannot read a package from a private GitHub repo, because the stage token is stripped. Composer then falls back to a source clone. That clone works only for a repo listed on the task. Any other private GitHub package fails to install.

Do not commit a `gitlab-token` or an `http-basic` entry for it. The relay adds the credential. The setup for the token is the same as for npm. See [GitLab package registry](https://codeherder.com/docs/package-downloads/#gitlab-package-registry).

If the cache is down, the proxy fetches Packagist metadata from the real host. It fetches a zipball from `codeload.github.com`, the host that the GitHub API redirects to. The stage never reaches `api.github.com` itself.

## Choose how PHP gets into the stage

The image build reaches only the Debian snapshot. PHP 8.5 comes from `packages.sury.org`, which is not in the snapshot. Each option below needs a different set of approved hosts. Only option A is proven, on one device. Options B and C are not proven.

| Option | Build hosts to approve | Notes |
| --- | --- | --- |
| A. Fragment with PHP and Composer | `packages.sury.org:443/connect` and the Composer download hosts | One image holds everything. Needs the most approvals. |
| B. Fragment with PHP only | `packages.sury.org:443/connect` | Declare Composer as an environment system package and mago as an environment tool. |
| C. Your own image `FROM php:8.5-cli` | None | Cannot combine with system packages. |

Debian packages in a fragment resolve from the snapshot. The environment keeps the snapshot sources in place through the fragment (image template 3). You can also move them out of the fragment with `ch env system add ca-certificates curl git unzip mariadb-server redis-server`.

The fragment rules refuse `FROM`, `ADD`, `COPY --from` and a heredoc (`stageenv.RefusedInstruction`). See [Giving stages the tools they need](https://codeherder.com/docs/stage-environments/#system-packages).

### Approve the build hosts

A build that needs a host fails and files a request. The task blocker names the host. Approve exactly the targets that the denial names. They can differ from the list below. Approve them in one batch, because each approval rebuilds the image.

```
ch egress rules create packages.sury.org:443 --purpose build --yes
ch egress list --purpose build --status pending
ch egress approve <requestId> --scope workspace
```

See [When a build needs another host](https://codeherder.com/docs/stage-environments/#when-a-build-needs-another-host). A rule applies to one workspace only. It does not pass down from a group.

## Option A: the fragment with PHP and Composer

Set it with `ch env system dockerfile --from-file php.Dockerfile`. The build hosts are:

| Host | Why |
| --- | --- |
| `packages.sury.org:443/connect` | The keyring and the PHP packages. Always needed. |
| `getcomposer.org:443/connect` | The Composer download. This is the host of the proven run. |

```
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl git unzip \
 && curl -fsSLo /tmp/sury-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
 && dpkg -i /tmp/sury-keyring.deb \
 && rm /tmp/sury-keyring.deb \
 && echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ trixie main" > /etc/apt/sources.list.d/php.list \
 && apt-get update \
 && apt-get install -y --no-install-recommends php8.5-cli php8.5-bcmath php8.5-curl php8.5-gd php8.5-intl php8.5-mbstring php8.5-mysql php8.5-redis php8.5-xml php8.5-zip mariadb-server redis-server \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSLo /usr/local/bin/composer https://getcomposer.org/download/2.9.5/composer.phar \
 && echo "c86ce603fe836bf0861a38c93ac566c8f1e69ac44b2445d9b7a6a17ea2e9972a  /usr/local/bin/composer" | sha256sum -c - \
 && chmod 0755 /usr/local/bin/composer
```

In this option the setup script installs `mago` only. Drop the Composer lines from the script, and keep the `mago` block.

## Option B: the fragment with PHP only

Use this option when you want one build host. The fragment installs PHP from sury and nothing from GitHub. Only `packages.sury.org:443/connect` needs approval.

```
RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl git unzip \
 && curl -fsSLo /tmp/sury-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
 && dpkg -i /tmp/sury-keyring.deb \
 && rm /tmp/sury-keyring.deb \
 && echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ trixie main" > /etc/apt/sources.list.d/php.list \
 && apt-get update \
 && apt-get install -y --no-install-recommends php8.5-cli php8.5-bcmath php8.5-curl php8.5-gd php8.5-intl php8.5-mbstring php8.5-mysql php8.5-redis php8.5-xml php8.5-zip mariadb-server redis-server \
 && rm -rf /var/lib/apt/lists/*
```

For option B, add Composer to the environment with `ch env system add composer`. Its version comes from the pinned Debian snapshot. Use option A when you need its explicit Composer 2.9.5 pin. Declare mago in the environment tool set as shown below.

## Option C: your own image

Build an image `FROM php:8.5-cli` and run the stage in it. The image build is yours, so the stage environment needs no build host. See [Running a stage in your own container image](https://codeherder.com/docs/stage-images/). A stage with its own image cannot also set system packages, so add MariaDB and Redis to your image. This option is also not proven.

### Reproducibility

Debian packages stay pinned to the snapshot. `packages.sury.org` is not pinned, so a rebuild can pick a newer PHP 8.5 patch. To pin one, name the version in the install line, as `php8.5-cli=<version>`. Read the exact version with `apt-cache policy php8.5-cli` in a built stage. Keep the sha256 beside every download.

Notes:

- The default image is Debian trixie. Its own PHP is 8.4, so the fragment adds the `packages.sury.org` repository for PHP 8.5.
- The suite name is fixed to `trixie`. The fragment does not read `lsb_release`.
- Change the extension list to what your `composer.json` requires. Run `composer check-platform-reqs` in a stage to see what is missing. PHP 8.5 always includes OPcache.
- Composer is the release `composer.phar`, with its sha256 pinned. Change both the version and the sha256 together.

### MariaDB or MySQL

The recipe uses MariaDB from Debian. It needs no extra repository, and its packages are signed by Debian. It serves PHPUnit suites that use the common MySQL feature set.

A suite that needs a MySQL-only feature, such as the `utf8mb4_0900_ai_ci` collation, needs real MySQL. Add the MySQL APT repository from `repo.mysql.com` to the fragment and install `mysql-server`. Then change the `mariadbd` commands below to `mysqld`.

## The setup script

Set it as `environment.before_stage`. It runs as the stage container’s entrypoint, so the services it starts stay up for the agent. It runs as the stage user, not as root. Tools must already be provisioned by the environment. See [the setup script](https://codeherder.com/docs/stage-images/#the-setup-script).

```
D=/tmp/ch-php-services
mkdir -p "$D/mysql" "$D/redis"

# Database and Redis, in user space. Nothing needs system root.
# mariadb-install-db makes a database root user. Connect as it with -u root.
mariadb-install-db --no-defaults --datadir="$D/mysql" --auth-root-authentication-method=normal --skip-test-db >"$D/install.log" 2>&1
nohup mariadbd --no-defaults --datadir="$D/mysql" --socket="$D/mysql.sock" --pid-file="$D/mysql.pid" --bind-address=127.0.0.1 --port=3306 >"$D/mysqld.log" 2>&1 &
nohup redis-server --bind 127.0.0.1 --port 6379 --dir "$D/redis" --save "" --appendonly no >"$D/redis.log" 2>&1 &
for _ in $(seq 1 60); do
  mariadb-admin --no-defaults --socket="$D/mysql.sock" ping >/dev/null 2>&1 && redis-cli ping >/dev/null 2>&1 && break
  sleep 1
done
mariadb --no-defaults -u root --socket="$D/mysql.sock" -e "CREATE DATABASE IF NOT EXISTS app; CREATE USER IF NOT EXISTS 'app'@'127.0.0.1' IDENTIFIED BY 'app'; GRANT ALL ON *.* TO 'app'@'127.0.0.1';"
```

Point your tests at `127.0.0.1:3306` with user `app` and password `app`, and at Redis on `127.0.0.1:6379`. A setup step that fails does not stop the stage, so read the `session.setup_script` event if a service is missing.

## Declare the tools in the environment

A human workspace admin pins mago once, using the version the project requires:

```
ch env tools add carthage-software/mago 1.30.0
ch env lock
ch env status
```

Wait for resolution and the device install to be ready before starting a stage. The environment lock records the download URL and checksum; the device provisions the tool on `PATH`. Do not download or install tool binaries in `before_stage`. Composer comes from option A’s environment image, option B’s environment system package, or option C’s custom image. See [Giving stages the tools they need](https://codeherder.com/docs/stage-environments/).

This environment-based mago recipe replaces the older setup-script download. The registry entry exists, but this revised recipe has not yet been verified in a live PHP stage.

## Run the project

```
composer install
mago lint
vendor/bin/phpunit
```

After `composer install`, check that `composer.lock` names `repo.packagist.org`, `api.github.com` and `gitlab.com`, and no `egress` host. The device refuses to push a `composer.lock` that names the sandbox cache. See [A push that names the cache is refused](https://codeherder.com/docs/package-downloads/#a-push-that-names-the-cache-is-refused).

## Trust and environment keys

PHP and Composer read `SSL_CERT_FILE`. The stage sets it to a bundle that holds the system roots and every run CA. Do not set it yourself. CodeHerder refuses `COMPOSER_CAFILE`, `COMPOSER_CAPATH` and `COMPOSER_HOME` as variables. `COMPOSER_HOME` can hold a global config that names a repository.

## Related pages

- [Package and browser downloads in container stages](https://codeherder.com/docs/package-downloads/)
- [Giving stages the tools they need](https://codeherder.com/docs/stage-environments/)
- [Running a stage in your own container image](https://codeherder.com/docs/stage-images/)
- [Isolating agent runs on a device](https://codeherder.com/docs/agent-isolation/)
