This project provides Docker images for PHP development environments, built on top of the wayofdev/docker-php-base images. It's designed to offer a convenient, feature-rich alternative to Laravel Sail for local development.
If you like/use this package, please consider βοΈ starring it. Thanks!
- Based on wayofdev/docker-php-base: Inherits all features and extensions from the base image.
- PHP Versions: Supports PHP
8.1
,8.2
,8.3
, and8.4
. - Image Types: Available in CLI, FPM, and Supervisord variants.
- Xdebug: Pre-installed and configured for debugging.
- Development Tools: Includes
git
,bash
,unzip
,nano
, and more. - Composer: Pre-installed for PHP dependency management.
- Time Manipulation: Includes
libfaketime
for testing time-dependent code. - Service Readiness: Includes
wait4x
for checking service availability. - Multi-architecture: Built for both AMD64 and ARM64 architectures.
On top of the extensions provided by the base image, this development image includes:
Extension | Description | Type |
---|---|---|
xdebug | Debugging extension | pecl |
Package | Type |
---|---|
git | apk |
bash | apk |
unzip | apk |
nano | apk |
faketime | apk |
wait4x | apk |
composer | bin |
phive | bin |
docker pull wayofdev/php-dev:8.3-fpm-alpine-latest
Replace 8.3-fpm-alpine-latest
with your desired PHP version, type, and tag.
- PHP Versions: 8.1, 8.2, 8.3, 8.4
- Types: cli, fpm, supervisord
- Architectures: amd64, arm64
# PHP 8.1 CLI
docker pull wayofdev/php-dev:8.1-cli-alpine-latest
# PHP 8.2 FPM
docker pull wayofdev/php-dev:8.2-fpm-alpine-latest
# PHP 8.3 with Supervisord
docker pull wayofdev/php-dev:8.3-supervisord-alpine-latest
Here's a more comprehensive example docker-compose.yml
for a Laravel project with additional services:
services:
app:
image: wayofdev/php-dev:8.3-fpm-alpine-latest
container_name: ${COMPOSE_PROJECT_NAME}-app
restart: on-failure
networks:
- default
- shared
depends_on:
- database
links:
- database
volumes:
- ./.github/assets:/assets:rw,cached
- ./app:/app:rw,cached
- ./.env:/app/.env
- ~/.composer:/.composer
- ~/.ssh:/home/www-data/.ssh
environment:
FAKETIME: '+2h'
XDEBUG_MODE: '${XDEBUG_MODE:-off}'
PHIVE_HOME: /app/.phive
dns:
- 8.8.8.8
extra_hosts:
- 'host.docker.internal:host-gateway'
web:
image: wayofdev/nginx:k8s-alpine-latest
container_name: ${COMPOSE_PROJECT_NAME}-web
restart: on-failure
networks:
- default
- shared
depends_on:
- app
links:
- app
volumes:
- ./app:/app:rw,cached
- ./.env:/app/.env
labels:
- traefik.enable=true
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.rule=Host(`api.${COMPOSE_PROJECT_NAME}.docker`)
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.entrypoints=websecure
- traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.tls=true
- traefik.http.services.api-${COMPOSE_PROJECT_NAME}-secure.loadbalancer.server.port=8880
- traefik.docker.network=network.${SHARED_SERVICES_NAMESPACE}
- An
app
service using thewayofdev/php-dev
image for PHP processing. - A
web
service using a custom Nginx image for serving the application. - Network configuration for both default and shared networks.
- Volume mounts for application code, assets, and configuration files.
- Environment variables for PHP and Xdebug configuration.
- Traefik labels for reverse proxy and SSL termination.
For a comprehensive, real-world example of how to use this image in a Docker Compose setup, please refer to the wayofdev/laravel-starter-tpl repository. This template provides a fully configured development environment for Laravel projects using the wayofdev/php-dev
image.
This project uses a set of tools for development and testing. The Makefile
provides various commands to streamline the development process.
- Docker
- Make
- Ansible
- goss and dgoss for testing
Clone the repository:
git clone [email protected]:wayofdev/docker-php-dev.git && \
cd docker-php-dev
Ansible is used to generate Dockerfiles and configurations. To generate distributable Dockerfiles from Jinja template source code:
make generate
-
Build the default image:
make build
This command builds the image specified by the
IMAGE_TEMPLATE
variable in the Makefile. By default, it's set to8.3-fpm-alpine
. -
Build a specific image:
make build IMAGE_TEMPLATE="8.3-fpm-alpine"
Replace
8.3-fpm-alpine
with your desired PHP version, type, and OS. -
Build all images:
make build IMAGE_TEMPLATE="8.1-cli-alpine" make build IMAGE_TEMPLATE="8.1-fpm-alpine" make build IMAGE_TEMPLATE="8.1-supervisord-alpine" make build IMAGE_TEMPLATE="8.2-cli-alpine" make build IMAGE_TEMPLATE="8.2-fpm-alpine" make build IMAGE_TEMPLATE="8.2-supervisord-alpine" make build IMAGE_TEMPLATE="8.3-cli-alpine" make build IMAGE_TEMPLATE="8.3-fpm-alpine" make build IMAGE_TEMPLATE="8.3-supervisord-alpine" make build IMAGE_TEMPLATE="8.4-cli-alpine" make build IMAGE_TEMPLATE="8.4-fpm-alpine" make build IMAGE_TEMPLATE="8.4-supervisord-alpine"
These commands will build all supported image variants.
This project uses a testing approach to ensure the quality and functionality of the Docker images. The primary testing tool is dgoss, which allows for testing Docker containers.
You can run tests using the following commands:
-
Test the default image:
make test
This command tests the image specified by the
IMAGE_TEMPLATE
variable in the Makefile (default is8.3-fpm-alpine
). -
Test a specific image:
make test IMAGE_TEMPLATE="8.3-fpm-alpine"
Replace
8.3-fpm-alpine
with your desired PHP version, type, and OS. -
Test all images:
make test IMAGE_TEMPLATE="8.1-cli-alpine" make test IMAGE_TEMPLATE="8.1-fpm-alpine" make test IMAGE_TEMPLATE="8.1-supervisord-alpine" make test IMAGE_TEMPLATE="8.2-cli-alpine" make test IMAGE_TEMPLATE="8.2-fpm-alpine" make test IMAGE_TEMPLATE="8.2-supervisord-alpine" make test IMAGE_TEMPLATE="8.3-cli-alpine" make test IMAGE_TEMPLATE="8.3-fpm-alpine" make test IMAGE_TEMPLATE="8.3-supervisord-alpine" make test IMAGE_TEMPLATE="8.4-cli-alpine" make test IMAGE_TEMPLATE="8.4-fpm-alpine" make test IMAGE_TEMPLATE="8.4-supervisord-alpine"
The test configurations are defined in goss.yaml
files, which are generated for each image variant. These files specify the tests to be run, including:
- File existence and permissions
- Process checks
- Port availability
- Package installations
- Command outputs
- PHP extension availability
When you run the make test
command, the following steps occur:
- The specified Docker image is built (if not already present).
- dgoss runs the tests defined in the
goss.yaml
file against the Docker container. - The test results are displayed in the console.
This project has a security policy.
Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to:
- π€ Suggest a feature
- π Report an issue
- π Improve documentation
- π¨βπ» Contribute to the code
You are more than welcome. Before contributing, kindly check our contribution guidelines.
- Twitter: Follow our organization @wayofdev and the author @wlotyp.
- Discord: Join our community on Discord.