G'day:
I need to do some PHP work, and for that I need to have a PHP dev environment. I'm very rusty when it comes to PHP - I've not touched it for 2-3 years or so and my old brain doesn't hold on to things very well - and since that time I have shifted to using Docker for my environments anyhow. I've never used PHP in Docker before. So there's a challenge. And what's this? PHP is now up to version 8.2, with 8.3 being tested. The last time I touched PHP 7.2 was the new thing (we were still mostly on 5.5 at that time, that said).
Therefore I have a mini project ahead of me:
- Get PHP8.2 running in a Docker container.
- Get Nginx running in a different container, proxying requests to the PHP one.
- Have Composer up and running.
- So I can install PHPUnit.
- And run some basic tests of the installation.
- With code-coverage reporting on the tests (code coverage requires a debug module to be installed and running too).
- Also get PHPMD and PHPCS running too.
- Bonus: be able to run the tests from my IDE, on my host machine.
Success here will be to be able to view the HTML code coverage report, served by Nginx, showing code being covered by testing.
Full disclosure: I did all this a few nights ago, and I am repeating the exercise now for the purposes of this article.
Application file structure
This shows the file system layout I'm aiming for:
/var/www# tree -L 1 . |-- docker |-- html |-- src |-- test `-- vendor 5 directories, 0 files /var/www#
- docker.Docker stuff like docker-compose.yml and sub-directories for the various containers' Dockerfiles and other config / assets are in here.
- html. Files that will be served by Nginx go in here.
- src. Application code goes here.
- test. Test code goes here.
- vendor. The app's Composer dependencies go in here.
This is all standard PHP-app stuff, except my personal decision of how to organise the Docker files.
PHP in a container
docker-compose.yml
The docker-compose.yml service definition is pretty simple:
version: "3"
services:
php:
build:
context: php
dockerfile: Dockerfile
stdin_open: true
tty: true
volumes:
- ..:/var/www
/var/www is the directory the container expected to see PHP stuff in, so I ran with it. It doesn't really matter.
.env
Oh I have a wee .env file too:
COMPOSE_PROJECT_NAME=php8
Just so the container names are a bit more on-point when they get created.
Dockerfile
The Dockerfile, on the other hand, is a bit complicated, and took me ages to google all the crap I needed to get together to make PHP 8.2 work in a container with a real-world set of extensions loaded, etc. Deep breath…
FROM php:8.2.1-fpm
RUN ["apt-get", "update"]
RUN ["apt-get", "install", "-y", "zip", "unzip", "git", "vim"]
COPY php.ini /usr/local/etc/php/php.ini
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
RUN pecl install xdebug && docker-php-ext-enable xdebug
COPY conf.d/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
COPY conf.d/error_reporting.ini /usr/local/etc/php/conf.d/error_reporting.ini
RUN apt-get install -y libicu-dev && docker-php-ext-configure intl && docker-php-ext-install intl
RUN ["apt-get", "install", "-y", "libz-dev", "libzip-dev"]
RUN docker-php-ext-configure zip && docker-php-ext-install zip
RUN docker-php-ext-configure bcmath && docker-php-ext-install bcmath
RUN docker-php-ext-configure pdo_mysql && docker-php-ext-install pdo_mysql
RUN docker-php-ext-configure opcache && docker-php-ext-install opcache
RUN curl -1sLf 'https://dl.cloudsmith.io/public/symfony/stable/setup.deb.sh' | bash
RUN ["apt-get", "install", "-y", "symfony-cli"]
WORKDIR /var/www
ENV COMPOSER_ALLOW_SUPERUSER 1
I'll go line-by-line, where there is anything noteworthy, or to explain my decisions.
- php-fpm. I readily concede I have no idea what all the tag variants of PHP images are on Docker Hub. But I have used php-fpm in the past and know it to work. So: running with it. I am specifically not using the Alpine variant as it doesn't come with BASH, and life is too short to negotiate ASH instead. And I am not trying to economise on disk space for this container anyhow.
- Baseline APT stuff. Composer needs zip, unzip and git (I learned this by trial and error). I need vim.
- PHP doesn't have a php.ini file by default although needs it. It ships with php.ini-development and php.ini-production, and it's down to the dev to pick which to use. This file is base on php.ini-development, with the following changes (mostly from recommendations from Symfony › Performance › Use the OPcache Byte Code Cache):
- realpath_cache_size = 4096k
- realpath_cache_ttl = 600
- date.timezone = Europe/London
- opcache.enable=1
- opcache.memory_consumption=256
- opcache.max_accelerated_files=20000
These are all just a matter of "uncommenting the example setting and tweak its value": normal php.ini stuff. No doubt I will further tweak that as I go, but that's a start. - Install Composer. It seems odd that Composer doesn't have the ubiquity that there's an APT package for it.
- Install Xdebug. PHPUnit needs this for code coverage analysis. Plus at some stage I might start coding like a grown-up and use line debugging. Maybe.
- I was following along the instructions on "Setup Step Debugging in PHP with Xdebug 3 and Docker Compose" to install Xdebug, and it suggested these settings to use. Yeah cool. I do not know any better. See below this list for the file contents.
- All of this lot are just libraries that the cited PHP extensions need to be able to run.
- The ultimate object of the exercise (well: the next part of the exercise) is to get Symfony installed in this app. Whilst setting up the PHP extensions I knew I would be wanting, I thought to look-up what Symfony would need too, and its guidance was to install the Symfony CLI and it would tell me (via symfony check:requirements. Hence installing this now. It was Symfony that reminded me to install all the highlighted extensions. handy. It's also handy that the PHP Docker image comes with those docker-php-ext-configure and docker-php-ext-configure utils, as it makes it a lot easier. There's also a bit of dependency-heck (not quite bad enough to use the work "hell" here) going on installing them, cos sometimes - like with libz-dev and libzip-dev - there are upsteam dependencies needed too. I think I got off pretty lightly here, just needing those two.
- /var/www is where I want to land when I start a shell on the container.
- I need to set this otherwise Composer complains about installing stuff as root. This'd be an issue in a production container, maybe. But it's not an issue on dev IMO.
Here are those PHP config files I mentioned above in the Xdebug bit:
# docker/php/conf.d/xdebug.ini
zend_extension=xdebug
[xdebug]
xdebug.mode=develop,debug,coverage
xdebug.client_host=host.docker.internal
xdebug.start_with_request=no
- I added coverage to this, for PHPUnit.
- The suggested setting for start_with_request was yes for this, but this meant IntelliJ would interrupt PHPUnit every time I ran my tests from the shell, so I've switched it off.
# docker/php/conf.d/error_reporting.ini
error_reporting=E_ALL
Normally I'd set this directly in php.ini, but I actually did this part of the config before I remembered about php.ini needing to be configured, so stuck with it.
After doing that lot I could build the container and bring it up, and run composer install:
/mnt/c/src/containers/php8/docker$ docker-compose build
[+] Building 4.0s (25/25) FINISHED
[...]
=> exporting to image 0.1s
=> => exporting layers 0.0s
=> => writing image sha256:3e9dfd6aca1527f8d0906a0d9f2b2ec2c74ddc0bd9ea9d2b8f0d8b1dce773951 0.0s
=> => naming to docker.io/library/php8-php 0.0s
/mnt/c/src/containers/php8/docker$ docker compose up --detach
[+] Running 2/2
⠿ Network php8_default Created 0.0s
⠿ Container php8-php-1 Started 0.5s
/mnt/c/src/containers/php8/docker$ docker exec -it php8-php-1 /bin/bash
/var/www# composer install
Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Package operations: 49 installs, 0 updates, 0 removals
- Downloading
[...]
Generating autoload files
41 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
/var/www#
/var/www# composer validate
./composer.json is valid
composer.json
Speaking of Composer, here's the composer.json file thusfar (don't worry too much about it: I'm including it here for completeness):
{
"name" : "adamcameron/php8",
"description" : "PHP8 containers",
"type" : "project",
"license" : "proprietary",
"require": {
"php" : "^8.2",
"ext-iconv": "*",
"ext-pdo_mysql": "*",
"ext-mbstring": "*",
"ext-intl": "*",
"ext-json": "*",
"ext-curl": "*",
"ext-simplexml": "*",
"ext-zip": "*",
"ext-pcre": "*",
"ext-ctype": "*",
"ext-session": "*",
"ext-tokenizer": "*",
"ext-bcmath": "*",
"ext-zend-opcache": "*",
"monolog/monolog": "^3.2.0",
"doctrine/dbal": "^3.5.3"
},
"require-dev": {
"phpunit/phpunit": "^9.5.28",
"phpmd/phpmd": "^2.13.0",
"squizlabs/php_codesniffer": "^3.7.1"
},
"autoload": {
"psr-4": {
"adamcameron\\php8\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"adamcameron\\php8\\test\\": "test/"
}
},
"scripts" : {
"test": "phpunit --testdox test",
"phpmd": "phpmd src,test text phpmd.xml",
"phpcs": "phpcs src test",
"test-all": [
"@test",
"@phpmd",
"@phpcs"
]
}
}
The require section there is not stuff I needed for the install, it's also a bunch of baseline stuff I know I will need for the app I'm heading towards. I don't think there's anything surprising there.
I also already have some PHPUnit, phpmd and phpcs scripts in there. I'll get to those next…
Testing the PHP container
It would not be me if I didn't test stuff. I will admit I did not TDD the bits above, cos that would just be mad. However I wanted to test things worked, so have put a few tests in. Plus part of this is testing the debug module and PHPUnit work together as well.
PHPUnit
Here's the phpunit.xml.dist file:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
colors="true"
cacheResult="false"
testdox="true"
stopOnFailure="true"
stopOnError="true"
stopOnWarning="true"
failOnWarning="true"
>
<coverage>
<include>
<directory suffix=".php">src</directory>
</include>
<report>
<html outputDirectory="html/test-coverage-report/" />
</report>
</coverage>
<testsuites>
<testsuite name="Integration tests">
<directory>test/integration/</directory>
</testsuite>
<testsuite name="Unit tests">
<directory>test/unit/</directory>
</testsuite>
</testsuites>
</phpunit>
All standard stuff, and there's nothing I can say about it that the docs don't already say.
Tests
A a few minimal tests, which hopefully are self-explanatory:
// test/integration/PhpTest.php
namespace adamcameron\php8\test\integration;
use PHPUnit\Framework\TestCase;
/** @testdox Tests of the PHP installation */
class PhpTest extends TestCase
{
/** @testdox It has the expected PHP version */
public function testPhpVersion()
{
$expectedPhpVersion = "8.2";
$actualPhpVersion = phpversion();
$this->assertStringStartsWith(
$expectedPhpVersion,
$actualPhpVersion,
"Expected PHP version to start with $expectedPhpVersion, but got $actualPhpVersion"
);
}
}
// test/integration/ComposerTest.php
namespace adamcameron\php8\test\integration;
use PHPUnit\Framework\TestCase;
/** @testdox Tests of the Composer installation */
class ComposerTest extends TestCase
{
/** @testdox It passes composer validate */
public function testComposerValidates()
{
exec("composer validate 2> /dev/null", $output, $returnCode);
$this->assertEquals(
0,
$returnCode,
"Composer validate failed: " . implode("\n", $output)
);
}
}
These two test three things: PHP is running the version I expect; Composer is happy it's configured properly; and PHPUnit itself is running otherwise all this would go splat.
For the code coverage testing I need some source code to test:
// src/Greeter.php
namespace adamcameron\php8;
class Greeter
{
public const FORMAL = 1;
public const INFORMAL = 2;
public static function greet(string $name, int $style = self::FORMAL): string
{
if ($style === self::FORMAL) {
return "Hello, $name";
}
return "Hi, $name";
}
}
And a test:
// test/unit/GreeterTest.php
namespace adamcameron\php8\test\unit;
use adamcameron\php8\Greeter;
use PHPUnit\Framework\TestCase;
/** @testdox Tests of the Greeter class */
class GreeterTest extends TestCase
{
/** @testdox It greets formally */
public function testFormalGreeting()
{
$name = "Zachary";
$expectedGreeting = "Hello, $name";
$actualGreeting = Greeter::greet($name, Greeter::FORMAL);
$this->assertEquals(
$expectedGreeting,
$actualGreeting,
"Expected greeting to be $expectedGreeting, but got $actualGreeting"
);
}
/** @testdox It greets informally */
public function testInformalGreeting()
{
$this->markTestSkipped("skipping this so the coverage report is more interesting");
$name = "Zachary";
$expectedGreeting = "Hey, $name";
$actualGreeting = Greeter::greet($name, Greeter::INFORMAL);
$this->assertEquals(
$expectedGreeting,
$actualGreeting,
"Expected greeting to be $expectedGreeting, but got $actualGreeting"
);
}
}
Note how I am skipping one of the tests. This is so code coverage is not 100%.
Running the tests
root@e8896f5d5bd6:/var/www# composer test > phpunit --testdox test PHPUnit 9.5.28 by Sebastian Bergmann and contributors. Tests of the Composer installation ✔ It passes composer validate Tests of the PHP installation ✔ It has the expected PHP version Tests of the Greeter class ✔ It greets formally ↩ It greets informally Time: 00:05.675, Memory: 10.00 MB Summary of non-successful tests: Tests of the Greeter class ↩ It greets informally OK, but incomplete, skipped, or risky tests! Tests: 4, Assertions: 3, Skipped: 1. Generating code coverage report in HTML format ... done [00:01.492] root@e8896f5d5bd6:/var/www#
Cool! It all worked. Let's have a look at the code coverage report. Because I don't have Nginx installed yet I can't browse to it, but I can just open the file in a browser:
I've drilled down the report slightly to show the file I was testing. It's correctly showing that I have only tested one path in the logic. Excellent. This proves that the Xdebug extension is running.
phpmd and phpcs
I've installed these too, and have used a fairly stock config file for each (see: phpmd.xml and phpcs.xml). Running them is dead boring as there's hardly any code, and IntelliJ makes sure it's formatted well:
/var/www# composer phpmd
> phpmd src,test text phpmd.xml
/var/www# composer phpcs
> phpcs src test
FILE: /var/www/src/Greeter.php
------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
------------------------------------------------------------------------------------------
18 | ERROR | [x] The closing brace for the class must go on the next line after the body
------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
------------------------------------------------------------------------------------------
Time: 2.51 secs; Memory: 6MB
Script phpcs src test handling the phpcs event returned with error code 2
/var/www#
Ha! I didn't actually expect that. I clearly didn't run this before I did my final commit. If you scroll up to the Greeter.php file, it's complaining that there's an empty line between the last method closing brace and the class's closing brace:
That breaks one of PRS-12's rules. Fair cop. And hey: a good test that it's working!
Nginx in a container
docker-compose.yml
The relevant bit is this:
nginx:
build:
context: nginx
dockerfile: Dockerfile
ports:
- "8008:80"
stdin_open: true
tty: true
volumes:
- ../html:/usr/share/nginx/html/
Nothing interesting there.
Dockerfile
FROM nginx:alpine
WORKDIR /usr/share/nginx/
COPY ./nginx.conf /etc/nginx/nginx.conf
COPY ./sites/ /etc/nginx/sites-available/
COPY ./conf.d/ /etc/nginx/conf.d/
CMD ["nginx"]
EXPOSE 80
Also nothing noteworthy here. Everything is in the config files.
Nginx config files
I freely admin to pretty much lifting these from other projects I already had. I don't really know what I'm doing with Nginx. I learn enough to achieve some goal, then I forget it all within about 5min.
// docker/nginx/nginx.conf
user nginx;
worker_processes 4;
daemon off;
error_log /var/log/nginx/error.log debug;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
access_log /var/log/nginx/access.log;
sendfile on;
keepalive_timeout 65;
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-available/*.conf;
}
// docker/nginx/conf.d/default.conf
upstream php-upstream {
server php:9000;
}
// docker/nginx/sites/default.conf
server {
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
server_name localhost;
root /usr/share/nginx/html;
index index.html index.php;
location / {
autoindex on;
try_files $uri $uri/ /index.php$is_args$args;
}
location ~ \.php$ {
try_files $uri /index.php =404;
fastcgi_pass php-upstream;
fastcgi_index index.php;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
fastcgi_param SCRIPT_FILENAME /var/www/html/$fastcgi_script_name;
fastcgi_read_timeout 600;
include fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}
I hope it doesn't seem dismissive or that I'm tired of writing in that I add nothing here. I literally don't know what most of that stuff does, other than where it's obvious.
A test PHP file to browse to
I need to be able to test that Nginx is passing stuff to PHP:
<?php
// html/test.php
phpinfo();
Having done all that, I rebuild the containers (and note I now have an Nginx one as well), and bring them up.
If I browse to http://localhost:8008/test.php, I get this:
And if I run the PHPUnit tests again, I can now browse to the report via http://localhost:8008/test-coverage-report/. Cool.
Success
OK so I'm gonna consider that a victory. I did some tinkering around in IntelliJ and I can run the unit tests from in there as well, all via drilling into the Docker container and running it from in there, and presenting the results in IntelliJ:
However that took more dicking around than I can be arsed with re-doing right now. I needed a coupla extensions installed, and set the PHP interpreter to be locatable via the config in docker-compose.yml. It's handy anyhow. I need my team to set all this up, so I'll get the first one of them I dump all this on to work it out and write it down, and I'll report back.
I've linked to all the individual files as I reference them, but you could also clone the repo, checkout the 1.0 tag, and you should be able to set this up locally and have a look if you so choose. There are full instructions in the readme.md file. I have had one of my team test the instructions out on their own PC, and they seemed to have worked.
Righto.
--
Adam
