# PHP

SlowShield serves Packagist at `https://slowshield.example.com/composer/`, as a Composer repository that replaces packagist.org. Projects keep their `composer.json` as it is; only where packages come from changes.

## Set it up

Two settings in Composer's global configuration cover every project on the machine: packagist.org off, and SlowShield on. One project can do the same in its own `composer.json`:

### Composer

Release age: Composer 2.11 adds its own (config.policy.cooldown.period, measured from Packagist's published-time, which SlowShield passes on). Composer 2.10 and older have none: SlowShield is the only layer.

*every project ($COMPOSER_HOME/config.json): packagist.org off, SlowShield on*

```
composer config -g repo.packagist false && composer config -g repos.slowshield composer https://slowshield.example.com/composer/
```

*one project's composer.json*

```
{
  "repositories": [
    {"type": "composer", "url": "https://slowshield.example.com/composer/"},
    {"packagist.org": false}
  ]
}
```

*a composer.lock written against packagist.org: point its dists at SlowShield (run next to it)*

```
php -r '$l = json_decode(file_get_contents("composer.lock"), true); foreach (["packages", "packages-dev"] as $k) foreach ($l[$k] ?? [] as $i => $p) if (isset($p["dist"]["reference"])) { $l[$k][$i]["dist"]["url"] = "https://slowshield.example.com/composer/dists/{$p["name"]}/{$p["dist"]["reference"]}.{$p["dist"]["type"]}"; unset($l[$k][$i]["notification-url"]); } file_put_contents("composer.lock", json_encode($l, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) . "\n");'
```

- **packagist.org has to be off.** Composer asks every repository, so a package SlowShield refuses would come from packagist.org instead. A repository named `packagist` doesn't replace it: Composer 2.10 adds it next to packagist.org.

- **Composer 2.10 or later.** Older versions clone a version from GitHub when its download is refused.

- **A project's own `repositories`** (`vcs`, `path`, other Composer repositories) still work, and don't go through SlowShield.

## What changes

- **The publish time** is each version's `published-time`, which Packagist sets. The `time` next to it comes from the package's author, so SlowShield never uses it. The first publish time SlowShield sees is kept, so it can't move earlier.

- **Held versions are left out** of the metadata, so `composer require` and `composer update` pick the newest version that is old enough.

- **A `composer.lock` that pins a held version** fails with `425 Too Early`, and Composer prints SlowShield's message, with the version to use instead:
   ```
   Warning from slowshield.example.com: slowshield: guzzlehttp/guzzle 8.3.0 is too new. It was published 2026-10-18T13:40:46Z (6.4 days ago); this proxy requires 7 days. It becomes available at 2026-10-25T13:40:46Z. Use an older version (composer update guzzlehttp/guzzle --with guzzlehttp/guzzle:8.2.0), or ask your SlowShield administrator for an exception.
   ```

- **Branches** (`dev-main`) count from their last push, so a branch pushed this week is held.

- **Brand-new packages** none of whose versions is old enough are held too: Composer doesn't fail open, because brand-new packages are the realistic attack (typosquats, dependency confusion).

- **Malware** from OSV and GitHub is refused with `451`. Packagist's own malware list reaches Composer through SlowShield, so Composer refuses those versions itself.

- **Downloads** come from SlowShield, which fetches them from GitHub, checks them against the first download and caches them. GitHub builds its archives on request; new bytes with the same files in them are the same download.

- **`composer audit` keeps working:** Packagist's advisories come through SlowShield.

## Lock files

A `composer.lock` written through SlowShield names SlowShield in its download URLs, so installing from it goes through SlowShield too. One written against packagist.org names api.github.com, and `composer install` downloads from GitHub, around SlowShield, even with packagist.org off. `composer update --lock` doesn't change that: it only writes GitHub, GitLab and Bitbucket URLs. The last snippet above points a lock's downloads at SlowShield and changes nothing else; run it next to `composer.lock` once, and commit the result.

## The second layer

Composer 2.11 adds a cooldown of its own, `config.policy.cooldown.period`, measured from the same `published-time`, which SlowShield passes on. Composer 2.10 and older have none, so SlowShield is the only layer.

## In Docker and CI

Set the repositories in the build stage. With a build argument, the same Dockerfile still builds without SlowShield when the argument is empty:

```
FROM composer:2 AS vendor
ARG COMPOSER_REPO=https://slowshield.example.com/composer/
RUN if [ -n "$COMPOSER_REPO" ]; then composer config -g repo.packagist false \
      && composer config -g repos.slowshield composer "$COMPOSER_REPO"; fi
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --no-scripts --prefer-dist
```

In CI, run the Setup page's command before `composer install`. [Building images](https://slowshield.org/docs/container-builds/) covers the base image too, and how to check that nothing in a build goes around SlowShield.

## Limits

- Checked with Composer 2.10.

- Not served: `composer search`, publishing, and Packagist's download statistics.

- Installs from source (`--prefer-source`, `preferred-install: source`) clone from GitHub, not through SlowShield.

- Block repo.packagist.org, api.github.com and codeload.github.com at the firewall for machines that should only use SlowShield.

---

This page as HTML: https://slowshield.org/docs/php/. All of the guide in one file: https://slowshield.org/llms-full.txt
