Skip to content

Docs: agents instructions, Makefile help and restyled readme #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
f3l1x wants to merge 8 commits into
base: master
Choose a base branch
from
Draft

Docs: agents instructions, Makefile help and restyled readme #30

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a09f7e9
Makefile: add help target and target descriptions
f3l1x Sep 28, 2026
7e1ec40
AI: add agents instructions
f3l1x Sep 28, 2026
63594e0
Editorconfig: init
f3l1x Sep 28, 2026
7e82fa5
Config: add fxnorm configuration
f3l1x Sep 28, 2026
8349a11
Readme: describe package, usage and development
f3l1x Sep 28, 2026
195cf1a
AI: simplify agents instructions to development essentials
f3l1x Sep 29, 2026
24cf1b5
AI: drop CLAUDE.md, agents read AGENTS.md directly
f3l1x Sep 29, 2026
121f5d5
Readme: simplify usage and development
f3l1x Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Readme: describe package, usage and development 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
  • Loading branch information
@f3l1x @claude
f3l1x and claude committed Sep 28, 2026
commit 8349a11bab2e066ebc90d7e39e2a2f8593c1b54d
194 changes: 112 additions & 82 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,147 @@
<h1 align=center>Dockette / PHP</h1>

<p align=center>
Ready-to-use Debian based images for PHP 5.6-8.5 with CLI or FPM and Composer preinstalled.
<a href="https://github.com/dockette/php/actions"><img src="https://github.com/dockette/php/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
<a href="https://hub.docker.com/r/dockette/php"><img src="https://img.shields.io/docker/pulls/dockette/php.svg" alt="Docker Hub pulls"></a>
<a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
<a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
</p>

<p align=center>
Trying to follow the latest releases with official PHP.
PHP 5.6 to 8.5 CLI and FPM images on Debian Bookworm, with <a href="https://getcomposer.org">Composer</a> 2 and about 25 extensions installed. PHP comes from the <a href="https://deb.sury.org">Sury</a> packages. For running PHP tools and applications in CI and local development, and as a base for your own images.
</p>

<p align=center>
🕹 <a href="https://f3l1x.io">f3l1x.io</a> | 💻 <a href="https://github.com/f3l1x">f3l1x</a> | 🐦 <a href="https://twitter.com/xf3l1x">@xf3l1x</a>
</p>

<p align=center>
<a href="https://github.com/dockette/php/actions"><img src="https://github.com/dockette/php/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
<a href="https://hub.docker.com/r/dockette/php"><img src="https://img.shields.io/docker/pulls/dockette/php.svg" alt="Docker Hub pulls"></a>
<a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
<a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
</p>

-----

## Usage

Install the Composer dependencies of the project in the current folder:

```sh
docker run --rm -v "$(pwd)":/srv dockette/php:8.5 composer install
```
docker run -v /path/to/site:/srv dockette/php:8.5
docker run -v /path/to/site:/srv dockette/php:8.5-fpm
docker run -v /path/to/site:/srv dockette/php:8.4
docker run -v /path/to/site:/srv dockette/php:8.4-fpm
docker run -v /path/to/site:/srv dockette/php:8.3
docker run -v /path/to/site:/srv dockette/php:8.3-fpm
docker run -v /path/to/site:/srv dockette/php:8.2
docker run -v /path/to/site:/srv dockette/php:8.2-fpm
docker run -v /path/to/site:/srv dockette/php:8.1
docker run -v /path/to/site:/srv dockette/php:8.1-fpm
docker run -v /path/to/site:/srv dockette/php:8.0
docker run -v /path/to/site:/srv dockette/php:8.0-fpm
docker run -v /path/to/site:/srv dockette/php:7.4
docker run -v /path/to/site:/srv dockette/php:7.4-fpm
docker run -v /path/to/site:/srv dockette/php:7.3
docker run -v /path/to/site:/srv dockette/php:7.3-fpm
docker run -v /path/to/site:/srv dockette/php:7.2
docker run -v /path/to/site:/srv dockette/php:7.2-fpm
docker run -v /path/to/site:/srv dockette/php:7.1
docker run -v /path/to/site:/srv dockette/php:7.1-fpm
docker run -v /path/to/site:/srv dockette/php:7.0
docker run -v /path/to/site:/srv dockette/php:7.0-fpm
docker run -v /path/to/site:/srv dockette/php:5.6
docker run -v /path/to/site:/srv dockette/php:5.6-fpm

Based on `dockette/debian:bookworm`. The working directory is `/srv`; mount your project there. The CLI images
run `php` by default and run as root.

Run PHP-FPM on port `9000`:

```sh
docker run --rm -p 9000:9000 -v "$(pwd)":/srv dockette/php:8.5-fpm
```

**Base image**
The FPM images run `php-fpm8.5` (or the matching version) in the foreground and log to stderr. They speak
FastCGI only, so put a web server such as Nginx or Caddy in front of them.

Use an image as the base for your own:

```Dockerfile
FROM dockette/php:8.5-fpm

RUN apt update && apt install -y curl
RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
```

## Documentation
The Sury repository is already configured, so more `php8.5-*` extension packages install the same way.

## Versions

Every version has a CLI tag and an `-fpm` tag. Each is built for `linux/amd64` and `linux/arm64` and rebuilt
every Monday. There is no `latest` tag; pin a version.

### Linux packages
| Tag | Base | Upstream EOL | State |
|-----|------|--------------|-------|
| `dockette/php:8.5`, `dockette/php:8.5-fpm` | `dockette/debian:bookworm` | 2029-12-31 | Supported |
| `dockette/php:8.4`, `dockette/php:8.4-fpm` | `dockette/debian:bookworm` | 2028-12-31 | Supported |
| `dockette/php:8.3`, `dockette/php:8.3-fpm` | `dockette/debian:bookworm` | 2027-12-31 | Supported |
| `dockette/php:8.2`, `dockette/php:8.2-fpm` | `dockette/debian:bookworm` | 2026-12-31 | Supported |
| `dockette/php:8.1`, `dockette/php:8.1-fpm` | `dockette/debian:bookworm` | 2025-12-31 | Legacy (EOL runtime) |
| `dockette/php:8.0`, `dockette/php:8.0-fpm` | `dockette/debian:bookworm` | 2023-11-26 | Legacy (EOL runtime) |
| `dockette/php:7.4`, `dockette/php:7.4-fpm` | `dockette/debian:bookworm` | 2022-11-28 | Legacy (EOL runtime) |
| `dockette/php:7.3`, `dockette/php:7.3-fpm` | `dockette/debian:bookworm` | 2021-12-06 | Legacy (EOL runtime) |
| `dockette/php:7.2`, `dockette/php:7.2-fpm` | `dockette/debian:bookworm` | 2020-11-30 | Legacy (EOL runtime) |
| `dockette/php:7.1`, `dockette/php:7.1-fpm` | `dockette/debian:bookworm` | 2019-12-01 | Legacy (EOL runtime) |
| `dockette/php:7.0`, `dockette/php:7.0-fpm` | `dockette/debian:bookworm` | 2019-01-10 | Legacy (EOL runtime) |
| `dockette/php:5.6`, `dockette/php:5.6-fpm` | `dockette/debian:bookworm` | 2018-12-31 | Legacy (EOL runtime) |

These images have preinstalled couple of linux packages: apt-transport-https ca-certificates git.
> [!WARNING]
> PHP 8.1 and older get no security fixes from upstream. The Legacy tags keep building while Debian Bookworm is
> supported; use them only to run old code.

### PHP extensions
## Packages

These images have preinstalled a couple of PHP extensions. The table shows which extension each version has.
The images include `apt-transport-https`, `ca-certificates`, `git`, `unzip` and Composer 2 in
`/usr/local/bin/composer`. Every version has the `cli`, `cgi` and `phpdbg` SAPIs; the `-fpm` tags add `fpm`.

The extensions per version:

| Extension | 5.6 | 7.0 | 7.1 | 7.2 | 7.3 | 7.4 | 8.0 | 8.1 | 8.2 | 8.3 | 8.4 | 8.5 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| apcu | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| bcmath | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| calendar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ctype | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| curl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| gd | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| geoip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| gettext | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| imagick | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| imap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| intl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ldap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| mbstring | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| mcrypt | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| memcached | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| mysql | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| pcov | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| pdo | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| pgsql | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| redis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| soap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| sqlite3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ssh2 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| xmlrpc | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| xsl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

All versions also have these SAPIs: cli, cgi and phpdbg. The `*-fpm` images have fpm in addition.

### Composer

![Composer](https://avatars3.githubusercontent.com/u/837015?v=3&s=200)

This super image has also preinstalled [Composer](https://getcomposer.org).

### Customization

In case of customization PHP 5.6 - 8.5:

- /etc/php/{5.6-8.5}/{cli,cgi,fpm}/conf.d/991-custom.ini
| apcu | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| bcmath | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| bz2 | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| calendar | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| ctype | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| curl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| gd | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| geoip | yes | yes | yes | yes | yes | yes | - | - | - | - | - | - |
| gettext | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| imagick | yes | yes | yes | - | - | - | - | - | - | - | - | - |
| imap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| intl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| ldap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| mbstring | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| mcrypt | yes | yes | yes | - | - | - | - | - | - | - | - | - |
| memcached | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| mysql | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| pcov | - | - | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| pdo | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| pgsql | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| redis | yes | yes | yes | yes | yes | yes | yes | yes | - | - | - | - |
| soap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| sqlite3 | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| ssh2 | yes | yes | yes | yes | - | - | - | - | - | - | - | - |
| xmlrpc | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| xsl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| zip | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |

## Configuration

Each image adds one `custom.ini`, stored in `/etc/php/{version}/mods-available/custom.ini` and linked as
`999-custom.ini` into the `cli`, `cgi` and (for `-fpm`) `fpm` config folders. It sets:

```ini
memory_limit = 521M
upload_max_filesize = 256M
post_max_size = 256M
date.timezone=Europe/Prague
```

The container time zone is also `Europe/Prague` (`TZ`). To change a setting, mount your own file over
`/etc/php/8.5/mods-available/custom.ini`, or add a file with a higher number to the `conf.d` folder.

The `-fpm` tags replace the Debian pool with `/etc/php/{version}/fpm/php-fpm.conf`: one `www` pool on port `9000`
as `www-data`, `pm = dynamic` with up to 9 children, `open_basedir` set to `/data:/srv:/var/tmp:/tmp` and
`clear_env = yes`. Put your application under `/srv` or `/data`, or PHP can't open its files. Extra pools go to
`/etc/php/{version}/fpm/pool.d/*.conf`.

## Development

Build and test the latest version, then run it with the current folder in `/srv`:

```sh
make build
make build VERSION=8.5-fpm
make test
make run
```

`VERSION` selects another version (`make build VERSION=8.4`); `make test` tests the CLI and FPM image of one
version, so build both first. `make help` lists all targets.

## Maintenance

See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider to [support](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.
See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider [supporting](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.
Loading