Dockerized PHP

A dockerized environment based on PHP-FPM running on a Linux Alpine container.

[TOC]

Summary

This repository contains a dockerized environment for building PHP applications based on php:8.3.4-fpm-alpine with -or without- Caddy support.

Highlights

• Unified environment to build CLI, web applications and/or micro-services based on PHP8.
• Allows you to create an optimized development environment Docker image
• Allows you to create an optimized production-ready Docker image
• If you are building web applications, this repository brings self-signed local domains thanks to Caddy.

Requirements

To use this repository you need:

• Docker - An open source containerization platform.
• Git - The free and open source distributed version control system.

Built with

Type	Component	Description
Infrastructure	Docker	Containerization platform
Service	Caddy Server	Open source web server with automatic HTTPS written in Go
Service	PHP-FPM	PHP with FastCGI Process Manager
Miscelaneous	Bash	Allows to create an interactive shell within main service
Miscelaneous	Make	Allows to execute commands defined on a Makefile

Getting Started

Just clone the repository into your preferred path:

$ mkdir -p ~/path/to/my-new-project && cd ~/path/to/my-new-project
$ git clone git@github.com:fonil/dockerized-php.git .

Conventions

Dockerfile

Dockerfile is based on multi-stage builds in order to simplify the process to generate the development container image and the production-ready container image.

Healthcheck

A custom health check shell script is provided to check the container service via HEALTHCHECK directive.

This shell script returns a SIGINT if the PHP-FPM service can handle a valid request to FPM ping status endpoint.

This health check directive is defined at Dockerfile instead of docker-compose.yml

Logging

The container service logs to STDOUT by default.

Directory structure

├── build                           # Docker-related configuration files
│   ├── Caddyfile                   # Caddy's configuration file
│   ├── healthcheck.sh              # Shell script for Docker's HEALTHCHECK  directive
│   └── www.conf                    # PHP-FPM configuration file
├── coverage                        # Code Coverage HTML dashboard
├── src                             # PHP application folder
├── caddy-root-ca-authority.crt     # Generated certificate file with Caddy Root CA Authority details
├── docker-compose.yml
├── Dockerfile
├── Makefile
└── README.md                       # This file

Development Environment

Volumes

There are some volumes created between the host and the container service:

Host path	Container path	Description
./src	/code	PHP Application folder
./coverage	/coverage	Code Coverage HTML dashboard folder

Those volumes can be customized in the docker-compose.yml file

Available Commands

A Makefile is provided with following commands:

~/path/to/my-new-project$ make

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║                           .: AVAILABLE COMMANDS :.                           ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

· build                          Docker: builds the service
· up                             Docker: starts the service
· restart                        Docker: restarts the service
· down                           Docker: stops the service
· logs                           Docker: exposes the service logs
· bash                           Docker: establish a bash session into main container
· install-caddy-certificate      Setup: installs Caddy Local Authority certificate
· show-context                   Setup: show context

Building the Docker image

To avoid any possible file permissions between the host and shared volumes with the container service, a non-root user is created into the container with same credentials than the host user. This internally created user is used to run the PHP-FPM service so any internally created file can be shared with the host without any file permission issue.

Those details are collected into the Makefile and passing each value to Dockerfile as a build argument:

Argument	How to fill the value	Description
HOST_USER_NAME	$ id --user --name	Current host user name
HOST_GROUP_NAME	$ id --group --name	Current host group name
HOST_USER_ID	$ id --user	Current host user ID
HOST_GROUP_ID	$ id --group	Current host user group ID

Accessing the container service

$ docker run -it --rm app:development bash

Web application

If you are developing web applications (which requires a web server) this repository brings a clean integration with Caddy, which uses HTTPS by default.

Website domain

The default website domain is https://website.localhost

Any .localhost TLD resolves by default to 127.0.0.1 so no any additional action is required on your host.

If you want to customize the default website domain please update the files build/Caddyfile and Makefile accordingly.

Certificate Authority (CA) & SSL Certificate

If you experiment any SSL certificate issue on your host, please register the Caddy Authority Certificate on your browser.

A Makefile command is provided called make install-caddy-certificate which guides you on this whole process.

This is a one-time action due the certificate does not change after rebuilding/restarting the service.

PHP Application

PHP application must be placed into src folder.

If you are starting a new application from scratch, please consider using PHP Skeleton

Testing

Mocking Date/Time functions

Testing with date and/or time variations sometimes can be a nightmare. To assist on this topic the UOPZ extension has been installed and enabled in the container.

You should add slope-it/clock-mock as a development dependency into your src/composer.json. This library provides a way for mocking the current timestamp used by PHP for \DateTime(Immutable) objects and date/time related functions.

Production Environment

Building the Docker image

$ docker buildx build --target=build-production --tag="app:production" .

Accessing the container service

$ docker run -it --rm app:production sh

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities:

PLEASE DON'T DISCLOSE SECURITY-RELATED ISSUES PUBLICLY

Supported Versions

Only the latest major version receives security fixes.

Reporting a Vulnerability

If you discover a security vulnerability within this project, please open an issue here. All security vulnerabilities will be promptly addressed.

License

The MIT License (MIT). Please see LICENSE file for more information.