HUB
Sign inSign up
php logo

kooldev/php

Sponsored OSS

By kool.dev

•Updated 1 day ago

PHP Images based on Alpine.

Image
2

500K+

kooldev/php repository overview

CI/CD

⁠Description

PHP Docker images focused on Laravel applications. They're intended for kool.dev⁠, but can fit other PHP use cases.

The images with Nginx include h5bp/server-configs-nginx⁠ with a hand picked set of configuration active by default. So if you want to change or add a new server configuration you can include h5bp/... as you see fit.

⁠Usage

Simplest example:

asciicast

⁠About composer

All images currently ship out with Composer 2.x as the default version. If for some reason you still need to use Composer 1.x and cannot make the upgrade, we still ship a composer1 in the images PATH as well, which is latest Composer 1.x version. Feel free to use it while you prepare to move to 2.0.

⁠Available Tags

The image built is kooldev/php⁠ which has a bunch of tags available:

The default images use Alpine Linux. PHP 8.4 and 8.5 also offer Debian Bookworm variants. All maintained tags are published for linux/amd64 and linux/arm64.

⁠8.5
⁠8.4
⁠8.3
⁠8.2
⁠Legacy versions

PHP 8.1, 8.0, and 7.4 are end-of-life upstream. Their tags remain on Docker Hub⁠, but are no longer built from this repository and receive no updates. Upgrade to a supported PHP version for new deployments.

⁠More flavours

We can always extend these images to suit them to our current use case. For example, we have a few extensions for specific use cases:

⁠Environment Variables

VariableDefault ValueDescription
ASUSER0Changes the user id that executes the commands
UID0Changes the user id that executes the commands (ignored if ASUSER is provided)
COMPOSER_ALLOW_SUPERUSER1Allows composer to run with super user
COMPOSER_MEMORY_LIMIT-1Changes composer memory limit
ENABLE_XDEBUGfalseEnables the Xdebug extension
PHP_DATE_TIMEZONEUTCChanges timezone used by date/time functions
PHP_MEMORY_LIMIT256MChanges PHP memory limit
PHP_MAX_INPUT_VARS1000 Changes how many input variables may be accepted on PHP
PHP_UPLOAD_MAX_FILESIZE25MChanges PHP maximum size of an uploaded file
PHP_POST_MAX_SIZE25MChanges PHP max size of post data allowed
PHP_MAX_EXECUTION_TIME30Changes PHP maximum time is allowed to run a script
PHP_FPM_LISTEN9000Changes the PORT address of the FastCGI requests
PHP_FPM_PMdynamicPHP-FPM process manager strategy
PHP_FPM_MAX_CHILDREN10Changes the number of child processes to be used on FPM
PHP_FPM_REQUEST_TERMINATE_TIMEOUT60Changes FPM timeout to serve a single request
⁠NGINX
VariableDefault ValueDescription
NGINX_LISTEN80Changes the PORT address
NGINX_ROOT/app/publicChanges NGINX root directive
NGINX_INDEXindex.phpChanges the index directive
NGINX_CLIENT_MAX_BODY_SIZE25MChanges maximum allowed size of the client request body
NGINX_PHP_FPMunix:/run/php-fpm.sockChanges the address of a FastCGI server
NGINX_FASTCGI_READ_TIMEOUT60sChanges a timeout for reading a response from the FastCGI server
NGINX_FASTCGI_BUFFERS8 8kChanges the number and size of the buffers used for reading a response
NGINX_FASTCGI_BUFFER_SIZE16kChanges the size of the buffer used for reading the first part of the response received
NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNEtrueEnables auto-tuning of worker processes based on available CPU cores (container instead of host), to disable set it to empty string
NGINX_HTTPSfalseEnables the HTTPS server
NGINX_LISTEN_HTTPS443Port for the HTTPS server to listen
NGINX_HTTPS_CERT/kool/ssl/_.localhost.pemThe path in the container for the SSL certificate file
NGINX_HTTPS_CERT_KEY/kool/ssl/_.localhost.keyThe path in the container for the SSL certificate key file

⁠Usage

With docker run:

docker run -it --rm kooldev/php:8.5 php -v

With environment variables:

docker run -it --rm -e ENABLE_XDEBUG=true kooldev/php:8.5 php -v

With docker-compose.yml:

app:
  image: kooldev/php:8.5
  ports:
    - "9773:9773"
  volumes:
    - ".:/app:cached"
    - "$HOME/.ssh/id_rsa:/home/developer/.ssh/id_rsa:cached"
  environment:
    ASUSER: "${UID:-1000}"

⁠Contributing

⁠Update images with templates

You should change fwd-template.json for configuration and template folder for the actual base templates.

After any changes, we need to run kool run template to parse the templates and generate all versions folder/files.

⁠Testing and publishing

Run bash scripts/test-image.sh 8.5 to test a locally built image (replace the tag for other variants). CI uses the same script for every image, building base images before their nginx and node variants so tests use the local base rather than a published tag.

CI builds and tests all 28 variants once per architecture on native ubuntu-24.04 (amd64) and ubuntu-24.04-arm (arm64) runners: 24 build/test groups. Only base builds pull their upstream PHP image fresh. Derived builds do not force-pull kooldev/php; the Docker driver keeps the fresh local base available to nginx/node builds. Before derived runtime tests, CI verifies that the local base still has its tested image ID and that its entire layer chain prefixes the derived image's layers. Tests use the build's immutable local image ID.

Pull requests, forks, and manual feature-branch runs never log in, stage images on Docker Hub, upload release metadata, publish stable images, or dispatch. Only trusted master runs (push, weekly schedule, or manual) stage the tested IDs under run/attempt-scoped tags. These temporary tags do not overwrite stable architecture tags. Staging tags remain in the registry; cleanup is not part of this workflow.

CI uses shared Bash/jq actions⁠, pinned in the workflow. PHP builds and runtime tests stay here.

Each native group uploads tested IDs/platforms and push digests in an images-RUN_ID-RUN_ATTEMPT-GROUP-ARCH artifact. The final publication job requires every group to succeed and downloads only the current attempt's metadata. It validates all 28 tags, exactly amd64 and arm64 per tag, repository, scope and digest format before changing any stable tag. Stable manifests reference those recorded digests; publication never rebuilds or uses QEMU. Dispatch starts only after every stable manifest succeeds.

Rerun the entire workflow, not just failed jobs: a new attempt cannot reuse metadata from an earlier attempt. Missing metadata fails closed before publication. Stable-tag updates across 28 tags are not a registry transaction: a registry failure during publication can leave a partially promoted release, but never triggers downstream dispatch. Investigate and rerun the whole workflow to recover.

Shared release contract and real loopback-registry tests run in the tooling repository using Bash. This repository runs the actual template generator before native builds and executes the runtime tests against immutable local image IDs. Synthetic registry tests are not substitutes for native runtime coverage.

PHP owns the rebuild schedule. After publication it notifies WordPress, SQL Server, and Swoole via docker-php-updated. Swoole notifies OCI8 only after all its images are published, so OCI8 does not race its Swoole parents or rebuild twice for the same PHP refresh. PHPQA is discontinued and no longer receives rebuild notifications. Downstream repositories have no separate cron schedules. Failed notifications must be investigated and retried manually; an accepted dispatch is not confirmation of downstream publication.

Repository or inherited organization secrets:

  • DOCKER_USERNAME and DOCKER_PASSWORD: Docker Hub credentials for publishing images and syncing this README.
  • Downstream dispatch uses DISPATCH_TOKEN when configured, otherwise the inherited WORKFLOW_TOKEN. The existing organization token normally avoids new credential setup; an optional dedicated DISPATCH_TOKEN can restrict access to the downstream repositories. The selected token needs permission to send repository dispatch events (fine-grained tokens need Contents write). Secret metadata does not establish token expiration or cross-repository permissions. If neither secret is available, the dispatch jobs fail visibly after images have been published.

⁠License

The MIT License (MIT). Please see License File⁠ for more information.

Tag summary

Content type

Image

Digest

sha256:37a6cad00…

Size

267.7 MB

Last updated

1 day ago

docker pull kooldev/php:8.4-oci8-swoole-nginx