# PHP / Composer

Avrea caches public Packagist metadata for Composer 2. Public GitHub distribution
archives can also use the shared package archive cache when package archive
caching is explicitly enabled. Existing `composer.lock` files and package
download URLs stay unchanged.

## On Avrea runners

Linux runners configure the default public Packagist repository when package
caching is enabled. Setup works before PHP or Composer is installed. Run your
usual `composer install` after installing the PHP version your project needs.

Setup respects `COMPOSER_HOME` and Composer's XDG/legacy home selection. It
preserves custom or disabled Packagist entries, private repositories,
`auth.json`, and plugin settings. Project-level repository settings keep their
normal precedence. If a workflow changes `COMPOSER_HOME` after runner setup,
configure the mirror in that home explicitly.

Automatic setup is currently limited to Linux. macOS, Windows, and job containers
require manual configuration and access to the cache with its CA trusted by PHP.

## Manual setup

For a Composer home that uses the default public Packagist repository:

```bash
composer config --global repositories.packagist.org composer https://cache.avrea.com:8443/composer
composer install
```

The cache hostname is reachable inside configured Avrea runners. Preserve an
existing custom Packagist entry instead of replacing it with this command.

PHP must trust the runner's cache CA. If using `COMPOSER_CAFILE`, `curl.cainfo`,
or `openssl.cafile`, use a CA bundle containing both public roots and the cache
CA. Keep HTTPS verification enabled. A workflow that supplies its own CA file
must include the cache CA there too.

To undo this manual configuration when the entry was previously absent:

```bash
composer config --global --unset repositories.packagist.org
```

Restore your previous value instead if one existed. Automatic runner cleanup
restores only the entry it owns and preserves subsequent user edits.

## Download coverage

Metadata caching follows the package cache setting. GitHub archive caching also
requires the separate, default-off package archive setting. Without that consent,
archive downloads continue upstream.

Eligible archives come from public GitHub repositories, use a full commit SHA,
and arrive without credentials, cookies, or query parameters. Private packages,
custom repositories, other archive hosts, and source checkouts continue using
their existing paths. Composer 1 metadata is unsupported.

GitHub API redirects and Packagist security APIs still contact upstream services.
`composer audit` and security policy checks remain enabled. Warm installs can
avoid repeated archive transfers while still making upstream requests.

## Cache stats

Composer has its own package-cache scope for metadata and archive hits, misses,
bytes, and errors. Archive diagnostics identify GitHub repositories and commits.
The proxy does not cache the project's `vendor/` directory.