"post-install-cmd": [
    "bin/console cache:clear --env=prod",
    "bin/console doctrine:migrations:migrate --no-interaction"
]

post-install-cmd runs during composer install, which in the production Dockerfile runs during the image build. There is no database available during a Docker build. The migration command either failed silently, or connected to nothing, or was skipped by Doctrine when it couldn’t find a schema to compare against. In any case, it didn’t migrate anything.

This is a clean violation of Factor XII : admin processes — migrations, one-off scripts, console tasks — should run in the same environment as the application, against the actual production data. Running them at build time inverts the relationship. The image shouldn’t know about the database. The database should be there when the image needs it.

The move to the entrypoint

The migration command moved from composer.json to docker-entrypoint.sh. The shift looks small on a diff. The implications are not.

The entrypoint runs when the container starts, not when the image is built. The database is reachable. The entrypoint waits for it — up to 60 seconds, one attempt per second — before doing anything:

ATTEMPTS_LEFT_TO_REACH_DATABASE=60
until [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ] || \
  DATABASE_ERROR=$(php bin/console dbal:run-sql -q "SELECT 1" 2>&1); do
    sleep 1
    ATTEMPTS_LEFT_TO_REACH_DATABASE=$((ATTEMPTS_LEFT_TO_REACH_DATABASE - 1))
done

if [ $ATTEMPTS_LEFT_TO_REACH_DATABASE -eq 0 ]; then
    echo "$DATABASE_ERROR"
    exit 1
fi

If the database doesn’t respond within 60 seconds, the container exits with an error and Kubernetes restarts it. Once the database is ready, the migration runs:

if [ "$( find ./migrations -iname '*.php' -print -quit )" ]; then
    php bin/console doctrine:migrations:migrate --no-interaction --all-or-nothing
fi

Two changes from the original command: --all-or-nothing ensures that if any migration in a batch fails, the entire batch rolls back. And the find guard skips the command entirely if there are no migration files — useful for services that don’t use Doctrine migrations at all.

This is genuinely better. The database is present. The migration runs in the real environment. The --all-or-nothing flag adds atomicity that the build-time version never had.

What it doesn’t solve

Two pods redeploying simultaneously both run the entrypoint. Both reach the database. Both find pending migrations. Both call doctrine:migrations:migrate.

Doctrine has a locking mechanism: a doctrine_migration_versions table that records which migrations have run, and the command checks it before applying. Under normal conditions this is fine: the second pod finds the table up to date and exits cleanly. The real failure modes are more specific: a migration long enough that the database lock times out before it completes, letting a second runner start the same migration before the first has finished; or a pod that crashes mid-migration before recording the version in the table, leaving the schema in an applied-but-unregistered state that the next pod will try to apply again.

The team’s position is explicit: a brief deployment downtime is acceptable. Application versions aren’t necessarily forward-compatible with older schema versions, so running N and N+1 simultaneously against the same database isn’t safe anyway. The deployment strategy is Recreate: all old pods are terminated before any new pods start. The migration runs on first startup, no overlap between versions. It works.

But “it works” and “it’s the right architecture” are different answers.

What would be different

Factor XII says admin processes should run in “one-off processes.” A process that runs once, for a specific purpose, against the production environment. The entrypoint is not one-off — it runs every time a container starts, including restarts, scaling events, and Kubernetes node movements.

Three alternatives exist, each with a different answer to the question of ownership:

A Kubernetes init container runs before the main container starts, in the same pod. It could run the migration, exit, and let the main container start only after it succeeds. The migration is isolated from the application runtime. The downside: the init container is another image to build and maintain, and it runs on every pod start — so a 14-service platform starting simultaneously still has a potential race.

A Kubernetes Job runs once, on demand or triggered by a deployment pipeline. It can be made to run before any pods are updated — serial, isolated, with a clear success or failure signal. The race condition goes away. The complexity moves to the deployment process: the Job must complete before the Deployment rollout begins, and the CI pipeline must coordinate both.

A Helm hook is the same concept expressed declaratively in the Helm chart. A pre-upgrade hook runs the migration before the application pods are updated. It’s the most idiomatic Kubernetes answer. It also means the Helm chart is now responsible for running migrations — a decision that belongs to whoever owns the chart.

That last sentence is why the entrypoint hasn’t changed. Moving migrations out of the application means deciding that the deployment infrastructure — not the application itself — is responsible for the schema. It’s a governance question as much as a technical one, and governance questions take longer to resolve than code changes.

The honest end

The migration block in the entrypoint is two lines. Literally: the if [ "$( find ./migrations... )" ] guard, and the php bin/console doctrine:migrations:migrate that follows. Eleven other factors have clean resolutions. The cache moved to Redis. The logs go to stdout. The filesystem is an S3 bucket. The CI assembles production images from the same commit it tests. The secrets don’t travel in image layers.

Factor XII has an answer. It’s just not the final one.

The migrations run at startup, with a real database, with atomicity, with a bounded retry window. That’s better than running at build time against nothing. Whether they eventually move to a Job or a Helm hook is a conversation about who owns the schema — a question that a kubectl apply can’t answer.

For the next forty seconds — out of a possible sixty — that container was polling for the database.

Requests that landed on it during that window got errors. Not many — the window was short — but enough to show up as noise in the monitoring. The kind of noise that gets dismissed as a transient network issue and filed nowhere. The deploy succeeded. The pod eventually became ready. The mechanism that caused it was still there, waiting for the next deploy.

The entrypoint script does five things before FrankenPHP starts: copy a version file, verify the vendor directory, wait up to sixty seconds for the database, run pending migrations, install assets and set filesystem permissions. In Docker Compose, this is invisible. In Kubernetes, the gap becomes traffic.

The gap between started and ready

Kubernetes decides whether to send traffic to a pod by watching its readiness probe. A pod whose readiness probe passes receives requests. A pod whose readiness probe fails is removed from the load balancer rotation until it recovers. This is the mechanism that makes rolling deploys safe: Kubernetes doesn’t cut over to a new pod until that pod says it’s ready.

The compose.yaml defines a healthcheck on every service:

healthcheck:
    test: [ "CMD", "php", "-v" ]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 10s

php -v succeeds the moment the PHP binary is present — which is true from the first millisecond of container life. The start_period: 10s gives ten seconds before checks begin. But the entrypoint polling loop runs for up to sixty seconds before FrankenPHP even starts. At second ten, the healthcheck passes. The application is still waiting for the database.

The Dockerfile has a better signal:

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1

Port 2019 is Caddy’s built-in metrics server, embedded directly in FrankenPHP. The endpoint is Prometheus-compatible and only responds once Caddy’s HTTP stack is fully initialized and PHP workers are accepting connections. php -v exits in fifty milliseconds regardless of what the application is doing — it checks the binary, not the server. :2019/metrics only answers when the server is actually serving. It is also not an endpoint added just for the probe: every service in the platform already has it scraped by Prometheus, so the signal is live regardless of any healthcheck configuration.

That’s closer. But in Kubernetes, the HEALTHCHECK instruction is ignored entirely. Kubernetes uses its own probe configuration. Without explicit probe definitions in the Kubernetes manifests, there are no readiness checks — and a pod is considered ready the moment its container starts.

Which means: pod starts, entrypoint begins polling, Kubernetes routes traffic, application is not yet serving. Requests arrive at a container that isn’t ready to handle them.

Three signals, three questions

Kubernetes separates container lifecycle into three distinct questions, each with its own probe type:

startupProbe — “Has the application finished starting?” Fires repeatedly until it passes, then hands off to liveness. Prevents the liveness probe from killing a container that’s legitimately slow to initialize. For a container whose entrypoint can take sixty seconds, this is the right tool.

readinessProbe — “Is the application ready to handle requests?” Fails and passes throughout the container’s life. When it fails, the pod is removed from the load balancer. This is what makes a rolling deploy safe.

livenessProbe — “Is the application still alive?” If it fails, Kubernetes restarts the container. Meant to catch hung processes, not slow startups.

The sixty-second polling loop belongs in the startupProbe’s patience, not in application code:

startupProbe:
    httpGet:
        path: /metrics
        port: 2019
    failureThreshold: 12    # 12 attempts × 5s = 60s max
    periodSeconds: 5

Once the startupProbe passes, a readinessProbe on the same endpoint takes over — telling Kubernetes when the pod is safe to receive traffic — and a livenessProbe watches for hung processes. But the startupProbe is the one that absorbs the slow start. The entrypoint polling loop becomes redundant: its job was to keep the container alive while the database caught up. Without it, the application attempts to connect, fails, and the container exits — Kubernetes restarts the pod, and the startupProbe maintains its retry cycle until the database responds and the application starts cleanly. The retry responsibility moves from inside the entrypoint to the orchestrator, which is exactly where it belongs.

The migration problem

The polling loop is the most visible issue, but the migrations create a subtler one.

With a rolling deploy and two replicas, Kubernetes starts a new pod while the old one still serves traffic. Both pods run the same entrypoint. Both reach doctrine:migrations:migrate.

Doctrine’s migration table tracks which migrations have already executed, so a completed migration won’t run twice. But if two pods start simultaneously and both see a pending migration, both attempt to run it at the same time. Whether that’s safe depends on the migration: additive schema changes are usually fine; destructive ones less so. And you don’t get to choose which ones run on a deploy that didn’t expect to coordinate. --all-or-nothing wraps migrations in a transaction and rolls back everything if one fails — it’s about atomicity within a single run, not coordination across processes.

The cleaner approach separates the two concerns into two init containers: one that waits for the database, one that runs migrations. The main container starts only after both complete:

initContainers:
    - name: wait-for-db
      image: authentication:latest
      command: ["php", "bin/console", "dbal:run-sql", "-q", "SELECT 1"]
    - name: migrate
      image: authentication:latest
      command: ["php", "bin/console", "doctrine:migrations:migrate", "--no-interaction", "--all-or-nothing"]

Both init containers reuse the application image. That’s not waste: they need the same PHP binary and the same environment wiring to reach the database and resolve the migration classes. A lighter purpose-built image would reduce startup overhead, but would require maintaining a separate PHP installation in sync with the main image.

Even with init containers, multiple pods starting simultaneously — initial deploy, after a node failure, or under autoscaling pressure — will each attempt to run migrations. Solving that properly — through a Helm pre-upgrade hook, a maxSurge: 0 strategy, or a separate migration Job — is a topic in itself. What matters here is that the entrypoint is the wrong place to host that decision: it can’t coordinate across pods, and it ties migration execution to application startup in a way that’s hard to untangle later. The question of which approach fits this codebase — and why the entrypoint hasn’t been replaced — gets its own treatment in the next article in this series .

Factor XII of the twelve-factor methodology — admin processes run in the same environment as the application — is satisfied either way. The question is whether “same environment” means “same entrypoint script” or “same image, separate process”. In Kubernetes, the latter is safer.

What the entrypoint’s real job is

Strip out the database wait (now a startupProbe or init container), the migrations (now an init container or Job), and the assets install (a build-time operation that belongs in the Dockerfile), and the entrypoint has one remaining job: start the application.

exec docker-php-entrypoint "$@"

Factor IX of the twelve-factor app asks for fast startup and graceful shutdown. A container whose startup takes sixty seconds because it’s waiting for external dependencies is not fast. It means rolling deploys are slow, recovery after a crash is slow, and horizontal scale-out creates a sixty-second gap before each new pod contributes.

Fast startup is not just a nice-to-have. It’s what makes the rest of the cloud model work. When a pod can start in seconds, the orchestrator can scale aggressively and recover quickly. When it takes a minute, you add headroom everywhere — longer probe timeouts, larger deployment windows, more conservative scaling policies — and the system becomes rigid.

The Docker Compose tax

The entrypoint accumulates these responsibilities for a reason. In Docker Compose, there is no init container concept. There is no startupProbe. Services declare depends_on, but without health conditions, that’s just startup ordering — not readiness. The entrypoint fills the gap.

This is not a design flaw. It’s a reasonable adaptation to the constraints of Docker Compose. The script works. It handles edge cases (the database timeout, unrecoverable errors, missing migrations directory). Someone tested it.

The issue is the assumption that the same script works equally well in Kubernetes. It runs. The application eventually starts. But it bypasses the probe system that makes Kubernetes deployments reliable, and it puts migration responsibility in a place where coordination across pods is difficult to reason about.

Several of the changes in this series — media storage , secrets in image layers , log handlers , service dependencies , CI environment parity , cache adapters — were changes to application code or configuration. This one is different. It requires the infrastructure to gain awareness of what “ready” means for this application, and it requires the entrypoint to give up responsibilities it currently owns.

That’s a harder conversation. But the startupProbe is waiting for it.

Then someone noticed the rate limiter was acting strange. Hit the API five times, get blocked. Hit it five more times on the next request, get through. Depending on which pod answered, you were a different person.

That was the cache talking. One config line, replicated across thirteen services, was blocking horizontal scaling entirely.

One config file, thirteen times

We were preparing a platform of thirteen Symfony microservices to move to Kubernetes. The stack was already in good shape: FrankenPHP for the HTTP server, multi-stage Dockerfiles, a GitLab CI that pushed tagged images to a cloud registry. The pieces were there. We just needed to verify nothing would break when we started scaling pods horizontally.

A good checklist for that kind of audit is the twelve-factor app methodology — twelve principles for building software that runs cleanly in cloud environments. Most factors were already covered without us doing anything deliberate about it.

Factor VII (port binding) came for free. FrankenPHP embeds Caddy directly into the PHP process. The container exposes its own HTTP endpoint, no Apache or Nginx to bolt on. The image is self-contained, which is exactly what the factor requires:

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1

Factor II (dependencies) was handled by composer.json and the Dockerfile extensions. Factor X (dev/prod parity) was covered enough for our scope: same image, same backing services locally and in CI, which is the part that actually matters for what we were auditing.

Then I got to Factor VI.

The problem with “it works on one server”

Factor VI says processes must share nothing. Nothing written to disk between requests, nothing in local memory that another instance can’t see. If you need to persist state, put it in a backing service — a database, a cache cluster, a queue. The process itself stays disposable.

I opened authentication/config/packages/cache.yaml. Then content/config/packages/cache.yaml. Then media/config/packages/cache.yaml.

framework:
    cache:
        app: cache.adapter.filesystem

Thirteen services. Thirteen times, word for word.

Every instance of every service was writing its cache to the local filesystem. Which meant every pod had its own private cache, invisible to every other pod. When the load balancer sent a request to pod A, it got pod A’s cached version of reality. Pod B had built its own. They might have been generated at different times, from different source data, or one of them might not have been built yet at all.

The rate limiter was the most visible symptom because it had a counter. But the same divergence affected every piece of data we were caching: serializer metadata, route collections, Doctrine result caches. Two users sending identical requests could get different responses depending on which node happened to pick up the connection.

Redis was already there

This is the part that stings a little. Redis was already in the stack. Every service had it configured via SncRedisBundle:

# config/packages/snc_redis.yaml — present on all 13 services
snc_redis:
    clients:
        default:
            type: 'phpredis'
            alias: 'default'
            dsn: '%env(IN_MEM_STORE__URI)%'

Factor IV of the twelve-factor app says backing services should be attached resources, interchangeable through configuration. Redis was exactly that: reachable via an environment variable, ready to be swapped for a managed instance in the cloud. The plumbing was done. We just weren’t using it for the application cache.

Some services even had it right for specific pools. The rate limiter in the authentication service:

pools:
    rate_limiter.cache:
        adapter: cache.adapter.redis

Which explains the inconsistency we saw first. The rate limit count went to Redis (shared across pods). The cache backing the rate limit check went to the filesystem (local to the pod). Two sources of truth, one invisible to the other.

The fix was one line per service:

framework:
    cache:
        app: cache.adapter.redis
        default_redis_provider: snc_redis.default

Thirteen files. Thirteen identical changes. The kind of fix that makes you feel like you should have caught it earlier, except it’s perfectly invisible when you’re running a single instance.

What needs to move to Redis

The filesystem cache violated Factor VI (processes carry local state they shouldn’t) and Factor VIII (you can’t scale out without sharing that state). They’re the same problem seen from two angles: VI describes what’s wrong, VIII describes what you can’t do because of it.

With a shared cache backend, a second pod is safe. The two pods build the same cache, see the same invalidations, agree on the same rate limits. You can add a third pod under load and remove it when traffic drops. The orchestrator handles it; the application doesn’t need to know.

Without it, horizontal scaling is a liability. More pods means more divergence, more “works on my machine” bugs that are impossible to reproduce locally because local only runs one container.

Sessions had the same problem — and potentially a worse one. Twelve of the thirteen services were using session.storage.factory.native — which writes sessions to the filesystem by default. A user whose request lands on pod A gets a session tied to pod A. Their next request goes to pod B. Session gone, they’re logged out. Only one service had RedisSessionHandler configured.

The partial mitigation is that most of the platform runs stateless JWT-based APIs, so session usage is limited. But “limited” isn’t “zero”. The services that do create sessions — authentication flows, temporary state during OAuth handshakes — have a user-visible failure mode waiting for the second pod. Either those sessions get moved to Redis, or the code that creates them gets removed. Leaving them as-is is a decision that waits for the first user whose session disappears without explanation.

The other kind of state

Redis fixes the cross-pod problem. FrankenPHP introduces a different one worth knowing about.

In the standard PHP-FPM model, each request forks a fresh process. Every in-memory object — every cached value, every computed result — dies with the response. The process is stateless by construction.

FrankenPHP has a worker mode that doesn’t follow that model. In worker mode, a single PHP process boots once, loads the kernel, wires the container, and handles multiple successive requests without restarting. Request throughput improves: no autoloader cold start, no container rebuild per request, fewer allocations. The tradeoff is that the PHP process now has a lifecycle that spans requests.

For cache, this adds a wrinkle. An array adapter or APCu pool accumulates entries across requests on the same worker. A cache invalidation pushed to Redis reaches the other pods immediately — but doesn’t clear what’s sitting in a worker’s in-process memory. Two requests on the same pod can see different things: one hits a warm in-memory entry, the next triggers a Redis fetch after the in-process entry expires.

The platform keeps worker mode disabled (APP__WORKER_MODE__ENABLED=false). It’s available — the infrastructure is there, the flag is wired — but it’s not active. The performance gain didn’t justify the audit. Every cache pool would need to be verified against worker-mode semantics; every place where state leaks between requests would become a potential bug.

The conservative position: keep PHP stateless at the process level even when the runtime doesn’t require it. Factor VI’s shared-nothing principle applies not just to the filesystem — it applies to the process itself.

What was already working

To be fair to the codebase: the Symfony Scheduler was already using Redis for distributed locks:

$schedule->lock($this->lockFactory->createLock('schedule_purge'));

In a multi-pod environment, you don’t want five instances running the same purge job simultaneously. The lock prevents it. Redis makes the lock visible across pods. Whoever wrote the scheduler knew exactly what they were doing.

The same reasoning just hadn’t propagated to the cache configuration — probably because when you’re running a single instance, cache.adapter.filesystem is invisible. It works, it’s fast, it requires zero configuration. The problem only appears at two.

The four questions

Factor VI catches most applications off guard during a cloud migration. Not because developers don’t know about stateless processes — they usually do — but because the filesystem is always there, and the problem stays hidden until you try to run a second instance.

Before scaling a Symfony service horizontally, four questions are worth answering:

• Where does the application cache go? (cache.adapter.filesystem needs to become cache.adapter.redis)
• Where do sessions go? (session.storage.factory.native needs Redis — or remove sessions entirely if you’re JWT-only)
• Does anything write to var/ at runtime that another pod would need to read?
• Is anything in your code path that needs to be mutually exclusive across pods? (if yes, that’s a job for the Symfony Lock component backed by Redis, not a local mutex)

If the answers all point to shared backing services, you’re ready. If any of them points to the local filesystem, production will find the pod that built its cache three hours ago and serve it to the user who least expects it.

stages:
  - build
  - provision
  - phpunit
  - phpmetrics
  - behat
  - deprovision
  - deploy

Before the first assertion ran, fifteen minutes had passed. Terraform had cloned an infrastructure repository, authenticated to Azure, and applied a VM configuration. Ansible had connected to the new VM, installed PHP, configured the application, wired up a database and a Redis instance. Then the tests ran. Then Terraform destroyed what Ansible had built.

For every pipeline. From every branch. For every pull request, from open to merge.

What those fifteen minutes were missing

The provision stage set up two services: PostgreSQL and Redis. Three services that the application depended on in production were absent: RabbitMQ, MinIO, and Varnish.

RabbitMQ processed all asynchronous work — 56 consumers across 14 microservices. MinIO handled media storage. Varnish fronted the HTTP cache. In CI, none of them existed. Tests that exercised message queuing or file storage had two options: skip these paths, or leave them untested until staging. Varnish is a different case: tests hit the application directly and intentionally bypass the cache layer, so its absence in CI is a deliberate choice rather than a gap.

This is the problem Factor X describes as the environment gap. The gap here wasn’t a matter of configuration — it was structural. The VM was built by Ansible from a script in a separate repository. It wasn’t a container image. It wasn’t versioned alongside the application. If a branch modified the RabbitMQ message topology, there was no way to test that modification in CI. The topology change and the code that relied on it would only meet in staging.

The Ansible provisioning script itself is part of the problem:

launch_vm:
  stage: provision
  script:
    - git clone git@gitlab.internal/infra/ci-vm.git
    - cd ci-vm
    - az login --service-principal -u $ARM_CLIENT_ID ...
    - terraform apply -var "prefix=${CI_PIPELINE_ID}-vm" ...
    - sleep 45
    - ansible-playbook behat/test-env.yml ...

The sleep 45 is there because Ansible needs the VM to finish booting before it can connect. It’s not an oversight — it’s the minimum time a freshly provisioned VM needs before SSH works. It’s baked into the process.

What replaced it

The new pipeline has no provision stage. It has no deprovision stage. The environment is the images, and the images exist before the tests begin.

Each test job declares its dependencies as Docker services:

services:
  - name: $REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG
    alias: rabbitmq
  - name: $REGISTRY_URL/platform/minio:$CI_COMMIT_REF_SLUG
    alias: minio
  - name: redis:7.4.1
    alias: redis
  - name: $ARTIFACTORY_URL/postgresql:13
    alias: postgresql

The services start in parallel when the job begins. Before the test script runs, a before_script waits for all of them to be ready:

before_script:
  - $CI_PROJECT_DIR/dockerize
      -wait tcp://postgresql:5432
      -wait tcp://rabbitmq:5672
      -wait tcp://minio:9000
      -wait tcp://redis:6379
      -timeout 120s

From pipeline start to first assertion: ninety seconds — assuming images are already cached on the runner; a cold pull adds time, but becomes negligible once the pipeline has run once on a given branch.

What $CI_COMMIT_REF_SLUG means

The timing is the visible result. What produces it is more interesting: the image names.

$REGISTRY_URL/platform/rabbitmq:$CI_COMMIT_REF_SLUG is not the official RabbitMQ image from Docker Hub. It’s an image built by the same pipeline, from the same branch, at the same commit as the code being tested. The RabbitMQ image carries the topology: a definitions.json with every exchange, every queue, every binding, every dead-letter configuration — versioned in git alongside the application that depends on them.

If a branch modifies the messaging topology, the CI pipeline builds a new RabbitMQ image that includes those modifications, then runs the tests against it. The topology change and the code that relies on it are tested together, at the same commit, before anything reaches staging.

The same logic applies to MinIO, as described in the first article in this series : the MinIO image carries preloaded test fixtures. The CI environment doesn’t need a setup step to populate storage. The state is built in.

The test runner itself follows the same pattern. Each job uses a debug variant of the application image — built from the same branch, same commit — with the test dependencies included:

image: $REGISTRY_URL/platform/$service:$CI_COMMIT_REF_SLUG-debug

The whole environment assembles from artifacts built at the same point in the git history.

What this required dropping

Behat and the provisioned VM were coupled. The Behat test suite ran against an HTTP server on the VM; removing the VM meant removing Behat.

That turned out not to be the obstacle it looked like. The Behat suite lived in a separate repository, required the VM to run, and had accumulated significant maintenance overhead. PHPUnit, running inside the application container with Docker services, covered the same scenarios through a more direct path: functional tests exercising the HTTP layer, unit tests for individual components, suites organized per feature area and generated dynamically into parallel CI jobs.

The BDD layer went away. The test coverage stayed — and could now run against the actual services.

Factor X, applied

Factor X is often read as “use the same database locally as in production.” That’s the simplest version. The deeper version is about the gap between what you test and what you ship.

The gap in the old pipeline was wide: a manually configured VM, missing key services, rebuilt from scratch on every run. The gap in the new pipeline is narrow: the CI assembles the environment from the same images as production, built from the same commit as the code under test.

The fifteen minutes of Terraform and Ansible were not just slow. They were building something that wasn’t what production ran, every time, before any test could begin. The ninety seconds of docker pull build exactly what production runs — and the tests that follow are testing that, not an approximation of it.

APP__GATEWAY__PRIVATE__HOST="platform.internal"
APP__GATEWAY__PRIVATE__PORT=80
APP__GATEWAY__PRIVATE__SCHEME="http"
APP__GATEWAY__PUBLIC__HOST="platform.internal"
APP__GATEWAY__PUBLIC__PORT=80
APP__GATEWAY__PUBLIC__SCHEME="http"

Thirteen services, six variables each, one value. Reading any service’s configuration, the architecture looked flat. Everything talked to the same host. That was the whole picture.

It wasn’t.

How the gateway worked

The gateway sat in front of every service and handled all inter-service traffic. A service calling the content API would construct a request to http://platform.internal/content/api/ — the gateway received it, identified the target from the URL path, and forwarded it to the right backend. Every inter-service HTTP client in framework.yaml followed the same pattern:

content.client:
    base_uri: "%http_client.gateway.base_uri%/content/api/"
    headers:
        Host: "%env(APP__GATEWAY__PRIVATE__HOST)%"

The http_client.gateway.base_uri parameter was assembled from the GATEWAY vars. The gateway knew where each service ran. The services didn’t need to know. From their perspective, everything was platform.internal.

This worked. For years, it worked well. Adding a service meant adding one DNS alias in the gateway config, not touching thirteen .env files. The gateway abstracted the topology. The services stayed decoupled from the infrastructure detail of who ran where.

What the gateway was absorbing

The abstraction had a cost that didn’t show up until you tried to read the system.

Looking at content’s env file, you saw six gateway variables and nothing else about inter-service communication. To find out that content called conversion, shorty, and media, you had to read framework.yaml. To find out that pilot called ten external services, you had to trace through the HTTP clients one by one and count.

The number was ten. Authentication, bam, config, content, conversion, media, product, shorty, sitemap, social. Ten of the platform’s thirteen services that pilot depended on at runtime, none of them visible from its configuration. Six variables said: talk to the gateway. They said nothing about the shape of what lay behind it.

That information existed — in the code, in the framework config, in the heads of the people who had built those integrations. It just didn’t live anywhere you could read at a glance.

What Kubernetes made explicit

On-premise, the gateway was a single resolvable hostname. One DNS record, one set of variables, one place to update. Kubernetes doesn’t work that way. Each service gets its own DNS name inside the cluster — content.namespace.svc.cluster.local, conversion.namespace.svc.cluster.local. Inter-service traffic goes directly, service to service, not through a shared gateway.

Moving to Kubernetes meant the gateway abstraction had to give way. Each service needed to know, concretely, where each of its dependencies lived. The six generic variables couldn’t express that.

The refactor replaced them with per-target HOST variables — one per service dependency, named for the target:

# content/.env — content calls these four services
APP__CONFIG__HOST="platform.internal"
APP__CONVERSION__HOST="platform.internal"
APP__MEDIA__HOST="platform.internal"
APP__SHORTY__HOST="platform.internal"

# pilot/.env — ten service dependencies
APP__AUTHENTICATION__HOST="platform.internal"
APP__BAM__HOST="platform.internal"
APP__CONFIG__HOST="platform.internal"
APP__CONTENT__HOST="platform.internal"
APP__CONVERSION__HOST="platform.internal"
APP__MEDIA__HOST="platform.internal"
APP__PRODUCT__HOST="platform.internal"
APP__SHORTY__HOST="platform.internal"
APP__SITEMAP__HOST="platform.internal"
APP__SOCIAL__HOST="platform.internal"

Each HTTP client in framework.yaml got its own base_uri built from its target’s HOST variable, and the Host header gave way to a User-Agent that identified the caller:

content.client:
    base_uri: "%env(APP__HTTP__SCHEME)%://%env(APP__CONTENT__HOST)%:%env(APP__HTTP__PORT)%/content/api/"
    headers:
        User-Agent: "Platform Content - %semver%"

The change isn’t cosmetic. In the old setup, the explicit Host header ensured requests reached the correct gateway virtual host regardless of URL resolution. In the new setup, each client points directly at its target’s DNS name — the right Host is derived from the base_uri automatically. The header slot doesn’t go empty: User-Agent now identifies the calling service, which surfaces in logs and distributed traces without any additional instrumentation.

The discomfort of legibility

pilot’s env file went from nine gateway variables to ten service-specific HOST variables. The file got longer. The architecture didn’t get simpler — the ten dependencies were there before and they’re still there now. What changed is that they’re readable.

Factor III says to store configuration in the environment. The old approach satisfied that literally: six variables, all in env files, none hardcoded. But variables that collapse the entire dependency graph into a single opaque hostname aren’t really configuration — they’re a shorthand that trades legibility for convenience. Factor III doesn’t ask only that configuration be externalized — it implicitly assumes the externalized configuration remains informative.

The refactor didn’t simplify anything. It made the complexity visible. pilot’s ten HOST variables document, in the .env file itself, the ten services it depends on. A new team member reading that file learns something real about the architecture. The old file taught them that there was a gateway.

There’s a version of this story where you read the final state and conclude the team did unnecessary work — they replaced six variables with ten, all pointing at the same host anyway. In local development, platform.internal still resolves to the same place. The functional behavior didn’t change.

The change is in what the configuration communicates. In Kubernetes, the HOST values diverge: each target gets its own cluster-internal DNS name, different per environment. The variables now carry real information. The refactor prepared the config to be honest about a topology it had been quietly simplifying for years.

What we didn’t have was any logs from the five minutes before the crash.

Promtail was running. It was healthy. It had been collecting logs from every other service without issue. But for this one, in the window that mattered, there was nothing. The service had crashed without leaving a trace.

The setup that looked correct

The logging stack was reasonable. Each service wrote structured JSON to stdout using Monolog’s logstash formatter:

stdout:
    type: stream
    path: "php://stdout"
    level: "%env(MONOLOG_LEVEL__DEFAULT)%"
    formatter: 'monolog.formatter.logstash'

Promtail collected container output via the Docker socket, parsed the JSON, extracted labels, pushed to Loki:

scrape_configs:
    -
        job_name: docker
        docker_sd_configs:
            -
                host: unix:///var/run/docker.sock
                refresh_interval: 5s
        pipeline_stages:
            -
                drop:
                    older_than: 168h
            -
                json:
                    expressions:
                        level: level
                        msg: message
                        service: service
            -
                labels:
                    level:
                    service:
        relabel_configs:
            -
                source_labels: [ '__meta_docker_container_log_stream' ]
                target_label: stream

Two stages in that pipeline do more work than the others. The json stage extracts level and service from each log line; the labels stage immediately following promotes them to Loki index labels, making {service="content", level="error"} a direct index lookup rather than a full-text scan across stored lines. The stream relabeling preserves whether a line came from stdout or stderr — a distinction that becomes queryable once Monolog sends errors to stderr and everything else to stdout. The drop older_than: 168h stage is a safety valve: if Promtail restarts after a long gap and replays buffered lines, anything older than seven days is discarded before reaching Loki.

In theory: logs go to stdout, Promtail reads stdout, logs appear in Loki. The twelve-factor app methodology describes exactly this model for Factor XI — treat logs as event streams, write to stdout, let the environment handle collection and routing.

The application had stdout. Promtail was reading stdout. What could go wrong.

What fingers_crossed takes with it

In production, the when@prod block replaced the simple stream handler with something more sophisticated:

when@prod:
    monolog:
        handlers:
            main:
                type: fingers_crossed
                action_level: error
                handler: main_group
                excluded_http_codes: [404]

The excluded_http_codes: [404] line is itself a tell: without it, every 404 from a scanner or crawler triggers a full buffer flush, dumping megabytes of debug logs for malformed URLs. Someone had already learned that the hard way.

fingers_crossed is a well-known Monolog pattern. The idea is elegant: don’t flood production logs with debug noise, but if something goes wrong, retroactively show what happened before the error. The handler buffers every log record in memory. The moment it sees an error, it flushes the entire buffer to the nested handler — giving you the full context leading up to the failure.

The problem is what happens when the failure isn’t a logged error. It’s an OOM kill. A SIGKILL from the orchestrator. A segfault. A process that stops responding and gets forcibly terminated.

In those cases, fingers_crossed never reaches its action_level. The buffer exists, full of the last five minutes of activity, and it vanishes with the process. The logs were there. They were in memory. They died before reaching stdout.

Factor IX of the twelve-factor app talks about disposability: processes should start fast and stop gracefully. On a clean shutdown (SIGTERM), a well-behaved process finishes its current work and exits. But crashes are not clean shutdowns, and memory buffers are not crash-safe. The service had been disposable in the sense that we could restart it; it was not disposable in the sense that its exit was transparent.

The files nobody was reading

There was a second problem, quieter but just as persistent.

Every service had a main_group handler that routed logs to two destinations in parallel:

main_group:
    type: group
    members: [main_file, stdout]

main_file:
    type: stream
    path: "%kernel.logs_dir%/%kernel.environment%.log"
    formatter: "monolog.formatter.logstash"

var/log/prod.log was being written on every service, in every environment, including production. The same content that went to stdout also went to a file inside the container. The file grew without rotation. The file was not accessible to Promtail (which read from the Docker socket, not from the container filesystem). The file consumed disk space. Nobody was reading it.

The audit channel was worse:

audit_file:
    type: stream
    path: "%kernel.logs_dir%/audit.log"
    formatter: 'monolog.formatter.line'

audit:
    type: group
    members: [audit_file, stderr]
    channels: ['audit']

Audit logs went to stderr (visible to Promtail) and to audit.log (not visible to Promtail). The format in the file was a plain line format, not the structured JSON that Promtail expected. In practice, the audit trail existed in two places: one queryable, one buried in a container directory that survived only as long as the container did.

What Factor XI actually requires

The eleventh factor is direct about this: an app should not concern itself with routing or storage of its output stream. It writes to stdout. Everything else is the environment’s job.

That means no file handlers in production. Not as a backup. Not for audit trails. Not “just in case”. The moment an application starts managing files, it takes on responsibility for rotation, retention, disk space, and accessibility — none of which belong inside a container.

The fix for the file handlers is straightforward. In when@prod, remove every *_file handler and every group that includes one. The audit channel gets the same treatment: stderr only, structured JSON, no file:

when@prod:
    monolog:
        handlers:
            stdout:
                type: stream
                path: "php://stdout"
                # defaults to "warning" — overridable per-deploy via env var for targeted debugging
                level: "%env(default:default_log_level:MONOLOG_LEVEL__DEFAULT)%"
                formatter: 'monolog.formatter.logstash'

            stderr:
                type: stream
                path: "php://stderr"
                level: error
                formatter: 'monolog.formatter.logstash'

            main:
                type: group
                members: [stdout]
                channels: ['!event', '!http_client', '!doctrine', '!deprecation', '!audit']

            audit:
                type: stream
                path: "php://stderr"
                level: debug
                formatter: 'monolog.formatter.logstash'
                channels: ['audit']

stdout for the main channel. stderr for errors and audit. Nothing else. Promtail picks up both via the Docker socket. The container writes nothing to disk. And audit logs are now structured JSON, queryable in Loki alongside everything else.

The harder question about fingers_crossed

The file handlers were easy. fingers_crossed is more nuanced.

The pattern solves a real problem: in a busy production service, logging everything at debug level creates noise and cost. fingers_crossed lets you capture context without paying for it unless something actually goes wrong. It is a reasonable tradeoff when the failure mode you’re protecting against is an application-level error (an exception, a 500, a slow query).

It is not a reasonable tradeoff when the failure mode is a process crash. And in a Kubernetes environment, process crashes happen: OOM evictions, liveness probe failures, node pressure. Exactly the cases where you most need the logs.

One approach: keep fingers_crossed but reduce the buffer size. By default it keeps everything since the last reset. Set buffer_size: 50 and you cap memory usage, which also limits what gets lost on crash. You won’t have the full context, but you’ll have the last fifty records. This patches the blast radius rather than removing the root cause: the opacity still depends on an error threshold that may never fire.

Another approach: accept that debug logs are expensive and raise the default log level in production. Then you don’t need fingers_crossed at all — if info and above go directly to stdout, nothing is ever buffered.

The approach we landed on: drop fingers_crossed, raise the default level to warning, keep a debug override available via env var for targeted investigation. The logs we care about appear immediately. The ones we don’t are never written. Nothing is buffered.

Crashes don’t flush

Factor XI and Factor IX meet at the same point: a process dying mid-request. another article in this series described the illusion of a service that worked perfectly on one pod but quietly misbehaved on two. This is the same illusion, one layer up: a service that appeared to log correctly, until the moment it most needed to.

The rule for production Monolog is blunt: if it doesn’t reach stdout or stderr before the process exits, it doesn’t exist. A file handler inside a container is invisible to the log collector and dies with the pod. A fingers_crossed buffer is invisible to the log collector and dies with the process.

Production tends to create the conditions where you need logs the most — OOM pressure, cascading failures, bad deploys — and those are exactly the conditions where both of these patterns fail you simultaneously. Write to stdout, default to a level that doesn’t require buffering, and make the override available for when you actually need to debug something. The logs will be there. They won’t be waiting for an error threshold that never fires.

docker run --rm <image> php -r "var_dump(require '.env.local.php');"

The output showed everything that composer dump-env prod had compiled into the image at build time. Which meant it showed everything that had been in the .env file when the image was built. Which meant it showed these, among others:

INFLUXDB_INIT_ADMIN_TOKEN=<influxdb-admin-token>
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=admin123
BLACKFIRE_CLIENT_ID=<blackfire-client-id>
BLACKFIRE_CLIENT_TOKEN=<blackfire-client-token>
BLACKFIRE_SERVER_ID=<blackfire-server-id>
BLACKFIRE_SERVER_TOKEN=<blackfire-server-token>
NGROK_AUTHTOKEN=replace-me-optionnal

Twenty-five variables in total. Every credential that had accumulated in the root .env over three years, now permanent in an image layer.

How dump-env works

composer dump-env prod is a legitimate Symfony optimization. Instead of parsing .env files on every request, the runtime loads a pre-compiled PHP array from .env.local.php. Faster and simpler.

The problem is what it reads. The Dockerfile copies the repository into the image with COPY . ./, .env included. Then dump-env prod reads that file and compiles every variable into .env.local.php. The image ships with a frozen snapshot of the credentials that were in .env at build time.

Docker layers are immutable archives. Even if a subsequent step removed .env from the container filesystem, the layer containing it would still exist inside the image. docker save <image> produces a tarball of every layer; extracting any file from any point in the build history is straightforward. The credentials are invisible at runtime. They are not gone.

Factor V calls this out directly: a build artifact should be environment-agnostic, with config arriving at the release step from outside. Once credentials are compiled in, the image is no longer portable. You can’t promote it across environments. You build twice and hope the second build behaves like the first.

How twenty-five variables accumulate

Before tracing how this gets fixed, it’s worth understanding how it happened.

The BLACKFIRE_* tokens are the easy case to understand. A team member sets up profiling, needs to share the configuration, and the repository is already open to everyone. One line in .env is the path of least resistance. The InfluxDB and Grafana credentials follow the same logic — shared tooling, shared repo, one commit.

Then there are the variables that reveal a different kind of drift. In some of the service-level .env files:

APP__RATINGS__SERIALS='{"brand1":{"fr":"12345"},...}'  # ~40 lines of JSON
APP__YOUTUBE__CREDENTIALS='{"brand1":{"client_id":"xxx","refresh_token":"yyy"},...}'

Audience measurement serial numbers. YouTube API refresh tokens per brand. These aren’t secrets in the Blackfire sense. They’re business data — the kind of values that vary between brands and environments, that someone decided to version in .env because they behaved like configuration and .env was where configuration lived.

Twenty-five variables is the sum of incremental decisions, none of which felt wrong in isolation. The problem is structural: when .env is the only answer available, everything starts looking like it belongs there.

Where things actually belong

Emptying the file required answering one question for each variable: where does this actually belong?

The answers revealed three categories that the team had never explicitly named:

Static config lives in code. Business rules, routing logic, Symfony parameter files — anything that doesn’t vary between deployments. A change requires a rebuild. The JSON blobs for audience measurement serials turned out not to be static config at all: they were queried from a dedicated Config service at runtime. They had no business being in a file.

Environment config varies between deployments: hostnames, connection strings, third-party credentials. This is what Factor III means by “config in environment variables” — real OS-level variables injected by the runtime, never files that travel with the code. In Kubernetes, this becomes a ConfigMap for non-sensitive values and a Kubernetes Secret for credentials. The choice for secrets management was SOPS — credentials are encrypted and committed to git, rather than stored in an external vault like Azure Key Vault or HashiCorp Vault. A vault trades simplicity for auditability: automatic rotation, centralized audit logs, workload identity-based access with no key to protect. SOPS trades those capabilities for a simpler operational model — no external service to query at deploy time, secrets travel through the normal code review process, git history serves as the audit trail. The accepted downsides are manual rotation and the responsibility of protecting the decryption key itself. For the team’s scale, the tradeoff was deliberate.

Dynamic config changes without a deployment: editorial parameters, per-brand thresholds, content moderation settings. It belongs in a database, managed through the application’s Config service. Some of what had accumulated in .env files was this category all along, passing as static defaults because it changed rarely enough that nobody noticed.

Once the categories had names, the variables sorted themselves. The root .env ended at four lines:

DOMAIN=platform.127.0.0.1.sslip.io
XDEBUG_MODE=off
SERVER_NAME=:80
APP_ENV=dev

Safe defaults. Nothing sensitive. dump-env prod now compiles empty strings; real values arrive at runtime from Kubernetes.

The PostgreSQL image

The PostgreSQL image used in CI has a hardcoded password:

FROM postgres:15
ENV POSTGRES_PASSWORD=admin123

This looks like the same problem. It isn’t, because the threat model is different. The CI database is ephemeral — it exists for the duration of a pipeline run, contains no real data, and runs in an isolated network. A hardcoded password on a throwaway test database is an acceptable risk, not a policy exception.

In production, the question doesn’t arise: the platform uses Azure Flexible Server, a managed PostgreSQL service. There is no Docker image. Credentials arrive via Helm chart injection, never touching a layer.

What survives the build now

The image that ships to production now contains a guarantee: var_dump(require '.env.local.php') returns only empty strings and safe defaults. The credentials aren’t there because they were never put there — they arrive at runtime, from outside.

That’s the responsibility boundary dump-env had been quietly erasing: the image is the application, the runtime is the environment. They should not know each other’s secrets.

These lines were in the production .env of the media service. Not staging. Not a local override. Production, committed to the repository, read on every startup.

The paths end where you’d expect: /media, /share_storage. They start somewhere more surprising: /home/jenkins-slave, the home directory of a CI runner from an old Jenkins setup.

How a runner’s home directory ends up in production config

The platform had grown from a single machine. One server ran everything — the application, the CI runner, the database, the file storage. Files moved between the app and the CI system via NFS: a directory mounted on the same host, accessible to both the containers and the runner.

The path /home/jenkins-slave/share_media was where the NFS share landed on that machine. When the team migrated to Docker Compose, the containers inherited the NFS mount. The path made it into the .env because the application needed to know where to find files. Nobody changed it because it worked. The mount was still there. The path was valid. The application started. Files appeared where they should.

Three years later, nobody thought about it at all. It was just how the media path was configured.

What kubectl apply found

The first kubectl apply for the media service ended with a pod stuck in CrashLoopBackOff. The container started. The entrypoint ran. The application tried to access /home/jenkins-slave/share_media/media. No such file or directory. No NFS mount. No runner.

The path didn’t document a design decision. It documented the machine that happened to be running at the time the .env was written.

This is what Factor IV of the twelve-factor app is warning against. Backing services — storage, queues, databases — should be attached resources, configured via URL or connection string, interchangeable between environments without code changes. A filesystem path on a shared host is not a backing service. It’s a physical assumption about the machine. When the machine changes, the assumption fails.

The path was the symptom

The obvious first step was removing the runner reference:

APP__COLD_STORAGE__FILESYSTEM_PATH="/share_media/media"
APP__SHARE_STORAGE__FILESYSTEM_PATH="/share_storage"

Cleaner. No more CI references in a production config. Still not right. The application still assumed a POSIX filesystem — either a volume mount or a directory on the node. In Kubernetes, a volume shared between multiple pods requires a ReadWriteMany PersistentVolumeClaim. Most storage providers don’t support it. Those that do tend to be slow and expensive. And even where it works, you’ve replaced one shared filesystem assumption with another.

Renaming the path bought time. It didn’t fix the problem.

The problem was that roughly twelve terabytes of images — originals and pre-generated derivatives in multiple formats — from multiple editorial brands — were treated as a directory. A directory can’t be mounted cleanly across pods. A backing service can.

Flysystem as the shape of the solution

The media service already had a Flysystem dependency. Three concrete adapters — local filesystem, AWS S3, Azure Blob — and one lazy adapter sitting on top:

# config/packages/flysystem.yaml
flysystem:
    storages:
        media.storage.local:
            adapter: 'local'
            options:
                directory: "/"

        media.storage.aws:
            adapter: 'aws'
            options:
                client: 'aws_client_service'
                bucket: 'media'
                streamReads: true

        media.storage:
            adapter: 'lazy'
            options:
                source: '%env(APP__FLYSYSTEM_MEDIA_STORAGE)%'

All application code depends on media.storage. It doesn’t know whether files live on the filesystem or in a cloud bucket. One environment variable determines which backend is active:

APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.aws   # production
APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.local  # local fallback still available

The path is gone. The filesystem assumption is gone. What remains is a service name — an attached resource in the twelve-factor sense, configurable without rebuilding the image.

The same pattern extends to the thumbnail cache. LiipImagine generates resized images on demand; both the source originals and the generated cache go through separate Flysystem adapters:

liip_imagine:
    loaders:
        default:
            flysystem:
                filesystem_service: 'media.storage'
        default_cache:
            flysystem:
                filesystem_service: 'media.cache.storage'

Two environment variables, two buckets. The full pipeline — receive upload, store original, generate thumbnail, cache it — is cloud-portable without touching a line of PHP.

What this doesn’t cover is moving the data. The lazy adapter changes one environment variable. Getting twelve terabytes from an NFS mount into an S3 bucket is a different project — a migration window, double-write during cutover, verification that nothing was missed.

What Minio makes possible in CI

Production uses S3. Local development uses Minio , an S3-compatible object store that runs in a Docker container. The AWS adapter talks to Minio locally and to S3 in production. The application doesn’t notice the difference:

# local/CI
APP__FLYSYSTEM_MEDIA_STORAGE=media.storage.aws
APP__MINIO_ENDPOINT=http://minio:9000
APP__MINIO_ACCESS_KEY=minioadmin
APP__MINIO_SECRET_KEY=minioadmin

The same code, the same adapter, a different endpoint. No mocking, no special test paths, no environment-specific branches.

But the CI configuration goes one step further. The Minio image used in the pipeline isn’t the standard upstream one — it’s a custom image built with test fixtures preloaded:

FROM minio/minio:latest
COPY tests/fixtures/ /fixtures_media/

Every CI run starts with a Minio instance that already contains the data the test suite expects. No setup script, no seed command, no “wait for fixtures to load” step before tests begin. The initial state of the test environment is part of the build artifact.

Factor V applied to test infrastructure: the environment state is built, versioned, and immutable. The CI pipeline builds the Minio image from the same source and at the same commit as the application image. The test fixtures and the code that exercises them are always in sync.

The S3 tradeoff, honestly

S3 introduces a latency cost that local storage doesn’t have. The first bytes of a file take 10 to 30 milliseconds to arrive from S3 — that’s the documented first-byte latency for the service, not a measurement on this specific workload.

At 300 requests per second, the reasoning for accepting it was this: most reads hit already-generated thumbnails in the S3-backed cache, not the original files. A freshly uploaded image pays the cold-miss penalty once, on the first thumbnail request. Everything after that is a cache hit. Whether the actual tail latency under load bore that reasoning out required performance testing that was tracked separately — the architecture decision and the validation were decoupled.

The tradeoff was accepted: predictable behavior across multiple pods, no shared-state problems, a storage layer that scales without coordination. The full measurement story belongs in the load test report, not here.

The ghost leaves

The path /home/jenkins-slave no longer appears in the configuration. But what it pointed to was a coupling that predated Docker, predated microservices, predated any conversation about cloud migration. The CI runner and the production application shared a filesystem because they lived on the same machine. Nobody designed it that way. It accumulated.

A kubectl apply error on a path that shouldn’t have existed forced the question: why does this application assume a specific CI runner is present on the host? The answer was “because it always has.” That’s not a reason. It’s a history.

Renaming the path was a paper fix. Flysystem’s lazy adapter was the actual answer — not because it’s more elegant, but because it makes the storage backend a decision that belongs to the environment, not to the application. The container starts, reads one variable, connects to whatever is at the other end. It doesn’t know whether that’s a bucket in a data center or a container on a laptop.

The runner’s home directory is gone from the config. What replaced it is a service name. That’s the difference.

Back then, Kubernetes didn’t exist yet. Options for running multiple services on a single machine came down to bash scripting, hand-written Nginx configs, and a lot of coffee. Tutorials on “homelab for humans” were nowhere to be found.

This tutorial is what I wish I had found back then. It’s been running for several years now. Not without evolving: services added, others dropped, choices revisited. But the foundation is there, stable — and that’s what success looks like in self-hosting.

The setup: ten self-hosted web services on a local machine, accessible from a browser via readable URLs, without touching DNS configuration, without renting a VPS, without managing TLS certificates. The ingredient that makes it possible: sslip.io , a public DNS service that encodes the IP directly in the domain name. service.192.168.1.10.sslip.io resolves to 192.168.1.10, with zero configuration, from any machine on the local network.

This tutorial is aimed at someone who knows Docker but is starting from scratch on self-hosted service orchestration.

Table of contents

1. Philosophy and architecture choices
2. The building blocks
3. Step-by-step setup
4. Adding a new service
5. Patterns and conventions
6. Common pitfalls
7. Conclusion
8. References

1. Philosophy and architecture choices

Goal

Run multiple web services on a local machine, accessible from a browser via readable URLs, without touching DNS configuration, without renting a VPS, without managing TLS certificates.

Why Docker Compose and not something else?

Docker Compose is the right level of complexity for a personal homelab. Kubernetes is too heavy for a single machine. Docker Swarm is in decline. Compose is simple, readable, versionable, and sufficient for dozens of services.

Why Traefik and not Nginx Proxy Manager?

Nginx Proxy Manager (NPM) is a graphical interface for configuring Nginx as a reverse proxy. Routes are stored in a database and configured through a UI.

Traefik automatically reads Docker container labels and generates its configuration on the fly. When a container starts with the right labels, Traefik discovers it and creates the route immediately, without restarting, without opening any UI.

This “configuration as code” approach has two major advantages:

• A service’s configuration lives in its compose.yaml, in the same place as everything else.
• Adding a service requires no changes to Traefik.

Why Dockge and not Portainer?

Portainer is a full Docker management tool: images, volumes, networks, individual containers… powerful but complex.

Dockge is focused on a single thing: managing Docker Compose stacks. Its UI is minimal and intuitive. For a homelab where everything is managed through Compose, it’s sufficient and much more pleasant to use.

Why sslip.io?

Web services need a hostname (e.g. dozzle.myserver.local) for Traefik to route correctly. The usual options:

• Edit /etc/hosts on every machine: tedious, not shareable.
• Set up a local DNS server (Pi-hole, AdGuard): requires additional infrastructure.
• Buy a domain and configure DNS: costs money and time.

sslip.io is a public DNS service that automatically resolves <anything>.<IP>.sslip.io to <IP>. Example: dozzle.192.168.1.10.sslip.io resolves to 192.168.1.10. Nothing to configure — the DNS works everywhere without touching anything.

2. The building blocks

The shared Docker network

All services and Traefik must share the same Docker network so Traefik can communicate with them. This network is called traefik and is created once:

docker network create traefik

It is an external network (created outside any Compose file). Each compose.yaml declares it as external:

networks:
    traefik:
        external: true

Why external rather than internal to a Compose file? Because multiple independent stacks all need to connect to it. A network internal to a Compose file is only accessible to services within that file.

Traefik: the reverse proxy

Traefik listens on port 80 and routes HTTP requests to the right container based on the Host header.

Its main configuration lives in stacks/traefik/docker/traefik/traefik.yaml:

api:
    dashboard: true
    insecure: true

entryPoints:
    web:
        address: :80
    ping:
        address: :8082

providers:
    docker:
        endpoint: unix:///var/run/docker.sock
        exposedByDefault: false

log:
    level: INFO

global:
    sendAnonymousUsage: false

exposedByDefault: false is important: Traefik ignores all containers by default. A container must explicitly opt in with the label traefik.enable: true. This prevents accidentally exposing services.

The ping entrypoint on port 8082 is dedicated to health checks. Separating it from the web entrypoint prevents health check requests from appearing in access logs.

To access the Docker daemon, Traefik mounts the socket:

volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Dockge: the stack manager

Dockge runs inside a container itself (the compose.yaml at the root of the repo). It needs two things:

1. Access to the Docker socket to manage the other containers.
2. Access to the stack directories to read and edit compose.yaml files.

The critical point is the stack mount. Dockge launches stacks by passing absolute paths to the Docker daemon. These paths must be identical inside the Dockge container and on the host. The solution:

volumes:
    - ${PWD}/stacks:${PWD}/stacks
environment:
    DOCKGE_STACKS_DIR: ${PWD}/stacks

${PWD} is a shell variable resolved at docker compose up time. It equals the current directory. If Dockge is launched from /home/user/homelab, the stacks folder will be mounted at /home/user/homelab/stacks on both sides. This is the only way to prevent Docker from creating ghost directories in the wrong place.

Practical consequence: always run docker compose up -d from the root of the repo.

Dockge’s persistent data (configuration, history) lives in a named volume created in advance:

docker volume create homelab_dockge_data

A named volume survives docker compose down -v. An anonymous volume would be destroyed with the stack.

3. Step-by-step setup

Step 1: clone and configure

git clone <repo> homelab
cd homelab

Find the machine’s local IP:

hostname -I | awk '{print $1}'
# e.g.: 192.168.1.10

Create and edit the root .env:

cp .env.example .env
# Edit .env:
# IP=192.168.1.10
# DOMAIN=sslip.io
# COMPOSE_PROJECT_NAME=dockge  ← important, see conventions section

Step 2: Docker prerequisites

docker network create traefik
docker volume create homelab_dockge_data

Step 3: start Dockge

echo "STACKS_DIR=$(pwd)/stacks" >> .env
docker compose up -d

Dockge is accessible at http://<IP>:5001. It is exposed directly on port 5001, not through Traefik (Traefik is not running yet at this point). Create an admin account on first launch.

Step 4: configure the stacks

For each directory in stacks/, copy the .env.example:

for stack in stacks/*/; do
    cp "${stack}.env.example" "${stack}.env"
done

Then edit each .env to set IP and DOMAIN to the same values as in step 1. The COMPOSE_PROJECT_NAME value is pre-filled with the folder name — do not change it (see conventions section).

For filebrowser, also set FILEBROWSER_ROOT to the local path to expose.

Step 5: start the stacks from Dockge

From the Dockge interface (http://<IP>:5001), in this order:

1. Traefik first

Traefik must be running before the other services. Without Traefik, routes don’t exist and services are unreachable via their URL.

After starting, verify Traefik is healthy:

docker ps --filter name=traefik

2. The other stacks in any order

Each stack automatically registers itself with Traefik via its Docker labels. Traefik discovers new containers in real time.

3. Homepage last

Homepage reads Docker labels from all running containers at startup to build the dashboard. Starting it last ensures it discovers all active services from the first launch.

4. Adding a new service

Here is the compose.yaml template for any new service:

services:
    myservice:
        image: vendor/myservice:latest
        restart: unless-stopped
        healthcheck:
            test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:<PORT>/ || exit 1"]
            interval: 30s
            timeout: 10s
            retries: 3
            start_period: 10s
        labels:
            # Homepage - auto-discovery in dashboard
            homepage.group: tools
            homepage.name: My Service
            homepage.icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/myservice.webp
            homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

            # Traefik - HTTP routing
            traefik.enable: true
            traefik.http.routers.myservice.entrypoints: web
            traefik.http.routers.myservice.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
            traefik.http.services.myservice.loadbalancer.server.port: <PORT>
        networks:
            - traefik

networks:
    traefik:
        external: true

And the associated .env.example:

COMPOSE_PROJECT_NAME=myservice
IP=127.0.0.1
DOMAIN=sslip.io

The folder name determines the subdomain. If the folder is called myservice, the service will be accessible at myservice.<IP>.<DOMAIN>. That’s it.

To find services worth adding, selfh.st is an excellent resource: it’s a catalog of self-hosted software organized by category (media, security, productivity, monitoring…), with a description, screenshot, and GitHub link for each. The site also publishes a weekly newsletter on new releases.

Checklist for a new service

• Create stacks/<subdomain-name>/compose.yaml
• Create stacks/<subdomain-name>/.env.example with COMPOSE_PROJECT_NAME=<name>
• Copy .env.example to .env and fill in IP/DOMAIN
• Check the port in the Traefik labels
• Choose the Homepage group: infra, monitoring, tools
• Find the icon on selfhst/icons
• Add persistent data in a volume if needed
• Start from Dockge and verify the container is healthy

5. Patterns and conventions

The ${COMPOSE_PROJECT_NAME} variable

Docker Compose automatically sets COMPOSE_PROJECT_NAME to the stack folder name. We use it to build URLs dynamically:

traefik.http.routers.dozzle.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

Advantage: no *_HOST variable to maintain in each .env. Renaming the folder automatically changes the subdomain.

Warning: in the .env, COMPOSE_PROJECT_NAME must be defined explicitly with the stack folder name. Without it, Docker Compose uses the current directory name at launch time, which can produce unexpected values depending on where the command is run from.

Homepage groups

Services are organized into three groups in the dashboard:

This grouping is specific to this homelab, not an enforced convention. Homepage accepts any value for homepage.group: you can create as many groups as needed and name them however you like (media, home-automation, dev…). The dashboard reorganizes automatically.

Health checks

All services have a health check. This is crucial because Traefik silently ignores unhealthy containers: a service with a failing health check will not appear in routing, even with traefik.enable: true.

Three edge cases encountered in practice:

1. localhost does not always resolve to 127.0.0.1

In some minimal images, localhost is not resolved. Use 127.0.0.1 explicitly:

test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/ || exit 1"]

2. Images without a shell (scratch-based)

Images based on scratch (e.g. Dozzle) do not contain /bin/sh. CMD-SHELL fails. Use the embedded binary:

test: ["CMD", "/dozzle", "healthcheck"]

3. Images without wget or curl

Some Node.js or JVM images have neither wget nor curl. Possible solutions:

• If Node.js is available: node -e "require('http').get('http://localhost:PORT', r => process.exit(r.statusCode < 400 ? 0 : 1)).on('error', () => process.exit(1))"
• If curl is available: curl -fs http://127.0.0.1:PORT/
• If the app binary exposes a healthcheck subcommand: use it directly.

Data persistence

For services that have data (configuration, user accounts, database):

volumes:
    - ./docker/data:/path/in/container

The ./docker/ folder lives inside the stack directory and can be versioned, except for runtime data which goes in .gitignore.

Rule: add stacks/<service>/docker/ to .gitignore if the folder contains data that should not be committed (SQLite databases, uploads…).

Traefik label conventions

By convention, the name used in Traefik labels (traefik.http.routers.<name>) matches the Docker service name in compose.yaml. In practice, align it with the folder name:

stacks/it-tools/    →    service: ittools    →    traefik.http.routers.ittools.*

This is not a technical constraint from Traefik, just a readability convention.

6. Common pitfalls

Dockge: Stop then Start, not Restart

When a compose.yaml is modified from an IDE and the changes need to be applied, use Stop + Start from Dockge, not “Restart”. Restart restarts the existing container without re-reading the compose.yaml. Stop + Start recreates the container with the new configuration.

Modified labels: restart Homepage

Homepage reads Docker labels at startup. If homepage.group or homepage.name is changed for a service, Homepage won’t see it until it is restarted.

Container starts but is not routable

Check in order:

1. docker ps: is the container healthy? Traefik ignores unhealthy containers.
2. Is the container on the traefik network?

docker inspect <container> --format '{{json .NetworkSettings.Networks}}'

3. Is the label traefik.enable: true present?
4. Does the Host(...) rule match the URL being tested?

Mounting non-existent files under Docker Desktop / WSL

When Docker Desktop (WSL) mounts a file that does not yet exist on the host, it creates a directory instead. This ghost directory then blocks the mount of the actual file. Symptom: the container fails to start with a mount error.

Solution: ensure the file exists on the host before starting the container, or use a directory mount instead of a file mount.

Watchtower: Docker API too old

On some configurations, Watchtower tries to communicate with the daemon starting the negotiation at API v1.25 (its historical minimum). Recent versions of Docker reject this version. Symptom: the container restarts in a loop with client version 1.25 is too old. Minimum supported API version is 1.40.

Fix in the Watchtower compose.yaml:

environment:
    DOCKER_API_VERSION: "1.40"

1.40 is the value to use, regardless of your Docker version. It is not your exact version — it is the minimum the daemon accepts, as stated in the error message. To check the actual API version of your daemon:

docker version --format '{{.Server.APIVersion}}'

${PWD} in Dockge’s compose file

${PWD} is not a .env variable — it is a shell variable resolved at docker compose up time. It equals the current terminal directory. Running docker compose up -d from any other directory will produce a wrong value and break stack volume mounts.

This homelab is designed to run on a Linux machine or WSL. All commands have been tested on Ubuntu/WSL2 with Docker Desktop.

Conclusion

I’m well aware this tutorial doesn’t cover everything. We could have added authentication in front of each service, run the whole thing over HTTPS, set up a socket proxy to limit the Docker daemon’s exposure, or pinned precise image versions. But each of those points would have considerably lengthened the article and the complexity of the setup. The goal was to start with something functional and maintainable, not to build a fortress on day one.

The perfect homelab doesn’t exist. The one that runs, does.

guillaumedelre/homelab

Docker Compose homelab with Traefik — independent stacks, auto-configured dashboard, and zero DNS configuration using sslip.io.

References

Native lazy objects

Symfony’s proxy system, used for lazy service initialization and Doctrine’s entity proxies, has historically relied on code generation. The proxy classes were generated at cache warmup, stored as files, and loaded when needed. It worked, but it added real complexity: generated files to manage, cache to invalidate, code that looked nothing like the class it proxied.

PHP 8.4 added native lazy objects. Symfony 8.0 uses them. The LazyGhostTrait and LazyProxyTrait that powered the old system are removed. Proxy creation is now a runtime operation backed by the engine itself, not a code generation step.

For application developers the change is mostly invisible: lazy services still work. For framework and library authors, a significant surface of complexity just disappears.

FormFlow

Multi-step forms have always been a DIY exercise in Symfony. Session management, step tracking, partial validation, navigation between steps: every project rolled its own solution or pulled in a third-party bundle.

8.0 introduces FormFlow: a built-in mechanism for multi-step form wizards. Steps are defined as a sequence of form types, partial validation is scoped to the current step, and session management is handled automatically.

#[AsFormFlow]
class CheckoutFlow extends AbstractFormFlow
{
    protected function defineSteps(): Steps
    {
        return Steps::create()
            ->add('shipping', ShippingType::class)
            ->add('payment', PaymentType::class)
            ->add('review', ReviewType::class);
    }
}

XML and fluent PHP config removed

The 7.4 deprecation of the fluent PHP configuration format becomes a hard removal in 8.0. XML configuration also exits as a first-class format. The supported formats for application configuration are now YAML and PHP arrays. The footprint shrinks, but what remains is genuinely better.

What else is gone

• PHP 8.2 and 8.3 support (8.4 minimum)
• The ContainerAwareInterface and ContainerAwareTrait
• Symfony’s internal use of LazyGhostTrait and LazyProxyTrait
• HTTP method override for GET and HEAD (only POST makes sense semantically)

Symfony 8.0 is a clean break, and that kind of break only becomes possible when the PHP floor rises. PHP 8.4’s lazy objects are the clearest example: the feature now exists in the language, so the framework can just stop implementing it.

Console becomes more ergonomic for invokable commands

Invokable commands get a significant upgrade. The #[Input] attribute turns a DTO into the command’s argument/option bag. No more calling $input->getArgument() inside the handler:

#[AsCommand(name: 'app:send-report')]
class SendReportCommand
{
    public function __invoke(
        #[Input] SendReportInput $input,
    ): int {
        // $input->email, $input->dryRun, etc.
        return Command::SUCCESS;
    }
}

BackedEnum is supported in invokable commands, so an option declared as a Status enum gets validated and cast automatically. Interactive commands get #[Interact] and #[Ask] attributes to declare question prompts inline. CommandTester works with invokable commands without any extra wiring.

Routing finds its own controllers

Routes defined via #[Route] on controller classes are auto-registered without needing an explicit resource: entry in config/routes.yaml. The tag routing.controller is applied automatically. You still control which directories are scanned, but your YAML config shrinks to a pointer at a directory rather than a manual file list.

#[Route] also gains a _query parameter for setting query parameters at generation time, and multiple environments in the env option.

Security: CSRF and OIDC get better tooling

#[IsCsrfTokenValid] gets a $tokenSource argument so you can specify where the token comes from (header, cookie, form field) rather than relying on a fixed convention. SameOriginCsrfTokenManager adds Sec-Fetch-Site header validation, a browser-native CSRF protection mechanism that doesn’t need token injection at all.

The security:oidc-token:generate command creates tokens for testing OIDC-protected endpoints locally. Multiple OIDC discovery endpoints are supported now, useful in multi-tenant setups where each tenant has its own identity provider.

Two new Twig functions: access_decision() and access_decision_for_user() expose the authorization voter result in templates without going through the security facade. #[IsGranted] can be subclassed for repeated authorization patterns that deserve their own named attribute.

ObjectMapper and JsonStreamer leave experimental

Both components introduced in 7.x graduate to stable in 8.0. ObjectMapper maps between objects without hand-written transformers, using attribute-based configuration. JsonStreamer reads and writes large JSON without loading the full document into memory, and it now supports synthetic properties: virtual fields computed at serialization time.

JsonStreamer also drops its dependency on nikic/php-parser. The code generation for the reader/writer now uses a simpler internal mechanism, cutting a heavy dev dependency.

Uid defaults to UUIDv7

UuidFactory now generates UUIDv7 by default instead of UUIDv4. The difference: v7 is time-ordered, so generated UUIDs sort chronologically. That matters a lot for database index performance. MockUuidFactory provides deterministic UUID generation in tests.

Yaml raises an error on duplicate keys

Previously, a YAML file with two identical keys silently kept the last one. 8.0 raises a parse error. This catches real bugs: duplicate keys in services.yaml or config/packages/*.yaml are almost always copy-paste mistakes and you definitely want to know about them.

Validator: Video constraint and wildcard protocols

A Video constraint joins the Image constraint for validating uploaded video files (MIME type, duration, codec). The Url constraint accepts protocols: ['*'] to allow any RFC 3986-compliant scheme, useful when storing arbitrary URLs that include git+ssh://, file://, or custom app schemes.

Messenger: SQS native retry and new events

SQS transport can now use its own native retry and dead-letter queue configuration instead of Symfony’s retry middleware. For high-volume queues on AWS, this removes a round-trip through PHP for transient failures. A MessageSentToTransportsEvent fires after a message is dispatched, carrying information about which transports actually received it.

messenger:consume gets --exclude-receivers to pair with --all.

Mailer: Microsoft Graph transport

A new transport sends mail via the Microsoft Graph API, which is what Microsoft recommends for applications on Azure Active Directory these days. The other options (SMTP relay, Exchange EWS) still work, but Graph is the right choice for new Azure deployments.

Workflow: weighted transitions

Transitions can now declare weights. When multiple transitions are enabled from the same place, the highest-weight one wins. This lets you express priority directly in the workflow definition without adding a guard that reads an external counter.

return (new Definition(states: ['draft', 'review', 'published']))
    ->addTransition(new Transition('publish', 'review', 'published', weight: 10))
    ->addTransition(new Transition('reject', 'review', 'draft', weight: 1));

Lock: LockKeyNormalizer

LockKeyNormalizer normalizes a lock key to a consistent string before hashing. Useful when the key is derived from user input or external data that may vary in whitespace or casing: the normalizer makes sure the same logical key always maps to the same lock.

HttpFoundation: QUERY method and cleaner body parsing

The IETF QUERY method (a safe, idempotent method with a body, unlike GET) is now supported throughout the stack: Request, HTTP cache, WebProfiler, and HttpClient. If you build search APIs that need a structured request body and also want caching, QUERY is the right semantic choice.

Request::createFromGlobals() now parses the body of PUT, DELETE, PATCH, and QUERY requests automatically.

Config: JSON schema for YAML validation

Symfony 8.0 auto-generates a JSON Schema file for each configuration section. IDEs that support JSON Schema for YAML files (VS Code, PhpStorm) can now validate config/packages/*.yaml against these schemas and provide autocompletion without any plugin. The schema is generated during cache warmup and placed at config/reference.php.

Runtime: FrankenPHP auto-detection

The Runtime component detects FrankenPHP automatically and activates worker mode without any extra package or environment variable. If $_SERVER['APP_RUNTIME'] is set, that runtime class takes precedence. You can also pick the error renderer based on APP_RUNTIME_MODE, which is useful when running the same codebase in HTTP and CLI contexts with different error presentation needs.

Message signing in Messenger

Transport security in Messenger has always been the application’s problem to solve. 7.4 adds message signing: a stamp-based mechanism that signs dispatched messages and validates signatures on reception.

The target use case is multi-tenant or external transport scenarios where you need cryptographic proof that a message wasn’t tampered with or injected from outside. Configuration lives at the transport level:

framework:
    messenger:
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                options:
                    signing_key: '%env(MESSENGER_SIGNING_KEY)%'

PHP array configuration

Symfony’s configuration formats have always been YAML (default), XML, and PHP. The PHP format existed but it was awkward: a fluent builder DSL that required method chaining and gave your IDE nothing useful to work with.

7.4 swaps the fluent format for standard PHP arrays. IDEs can now actually analyze it, config/reference.php is auto-generated as a type-annotated reference, and the result reads like data rather than code:

return static function (FrameworkConfig $framework): void {
    $framework->router()->strictRequirements(null);
    $framework->session()->enabled(true);
};

The fluent format is deprecated. Arrays are the future, and honestly it’s a better format.

OIDC improvements

#[IsSignatureValid] validates signed URLs directly in controllers, cutting out the boilerplate of manual validation. OpenID Connect now supports multiple discovery endpoints, and a new security:oidc-token:generate command makes dev and testing a lot less painful.

The support window

7.4 LTS: bugs until November 2028, security fixes until November 2029. The path to 8.4 LTS (the next long-term target) goes through 7.4’s deprecation notices and the PHP 8.4 upgrade. Fix the deprecations now and the jump to 8.x will be much less painful.

Attributes get more precise

#[CurrentUser] now accepts union types, which matters in practice when a route can be reached by more than one user class:

public function index(#[CurrentUser] AdminUser|Customer $user): Response

#[Route] accepts an array for the env option, so a debug route active only in dev and test no longer needs two separate definitions. #[AsDecorator] is now repeatable, meaning one class can decorate multiple services at once. #[AsEventListener] method signatures accept union event types. #[IsGranted] gets a methods option to scope an authorization check to specific HTTP verbs without duplicating the route.

Request class stops doing too much

Request::get() is deprecated, and honestly good riddance. The method searched route attributes, then query parameters, then request body, in that order, silently returning whatever it found first. That ambiguity caused real bugs. It’s gone in 8.0; in 7.4 it still works but triggers a deprecation. The replacements are explicit: $request->attributes->get(), $request->query->get(), $request->request->get().

Body parsing for PUT, PATCH, DELETE, and QUERY requests arrives at the same time. Previously Symfony only parsed application/x-www-form-urlencoded and multipart/form-data for POST. Those same content types now get parsed for the other writable methods too, which kills a common REST API workaround.

HTTP method override for GET, HEAD, CONNECT, and TRACE is deprecated. Overriding a safe method with a header was always semantically broken anyway. You can now explicitly allow only the methods that make sense for your app:

Request::setAllowedHttpMethodOverride(['PUT', 'PATCH', 'DELETE']);

Workflows accept BackedEnums

Workflow places and transitions can now be defined with PHP backed enums, both in YAML (via the !php/enum tag) and in PHP config. The marking store works with enum values directly, so your domain model and your workflow definition finally use the same types:

framework:
    workflows:
        blog_publishing:
            initial_marking: !php/enum App\Status\PostStatus::Draft
            places: !php/enum App\Status\PostStatus
            transitions:
                publish:
                    from: !php/enum App\Status\PostStatus::Review
                    to: !php/enum App\Status\PostStatus::Published

Extending validation and serialization for third-party classes

Ever needed to add validation or serialization metadata to a class from a bundle you don’t own? 7.4 has #[ExtendsValidationFor] and #[ExtendsSerializationFor] for that. You write a companion class with your extra annotations, point the attribute at the target class, and Symfony merges the metadata at container compilation time:

#[ExtendsValidationFor(UserRegistration::class)]
abstract class UserRegistrationValidation
{
    #[Assert\NotBlank(groups: ['my_app'])]
    #[Assert\Length(min: 3, groups: ['my_app'])]
    public string $name = '';

    #[Assert\Email(groups: ['my_app'])]
    public string $email = '';
}

Symfony verifies at compile time that the declared properties actually exist on the target class. A rename won’t silently break your validation.

DX: the things that don’t headline but matter

The Question helper in Console accepts a timeout. Ask the user to confirm something, and if they don’t respond in N seconds, the default answer kicks in. Very handy in deployment scripts that can’t afford to wait forever for a human.

messenger:consume gets --exclude-receivers. Combined with --all, it lets you consume from every transport except specific ones:

bin/console messenger:consume --all --exclude-receivers=low_priority

FrankenPHP worker mode is now auto-detected. If the process is running inside FrankenPHP, Symfony switches to worker mode automatically. No extra package needed.

The debug:router command hides the Scheme and Host columns when all routes use ANY, which removes a lot of noise from the default output. HTTP methods are now color-coded too.

Functional tests get $client->getSession() before the first request. Previously you had to make at least one request to access the session, which was annoying. Now you can pre-seed CSRF tokens or A/B testing flags up front:

$session = $client->getSession();
$session->set('_csrf/checkout', 'test-token');
$session->save();

Lock: DynamoDB store

DynamoDbStore lands as a new Lock backend. Useful in AWS-native deployments where Redis isn’t in the stack, and it works exactly like any other store:

$store = new DynamoDbStore('dynamodb://default/locks');
$factory = new LockFactory($store);

Doctrine bridge: day and time point types

Two new Doctrine column types: day_point stores a date-only value (no time component) and time_point stores a time-only value, both mapping to DatePoint. Good when your domain genuinely separates date from time:

#[ORM\Column(type: 'day_point')]
public DatePoint $birthDate;

#[ORM\Column(type: 'time_point')]
public DatePoint $openingTime;

Routing: explicit query parameters

The _query key in URL generation lets you set query parameters explicitly, separate from route parameters. This matters when a route parameter and a query parameter share the same name:

$url = $urlGenerator->generate('report', [
    'site' => 'fr',
    '_query' => ['site' => 'us'],
]);
// /report/fr?site=us

WebLink: parsing incoming Link headers

HttpHeaderParser parses Link response headers into structured objects. Before this, parsing Link headers from API responses meant either pulling in a third-party library or writing regex. The use case is HTTP APIs that advertise related resources or pagination via Link headers, like GitHub’s API does.

HTML5 parsing gets faster on PHP 8.4

DomCrawler and HtmlSanitizer switch to PHP 8.4’s native HTML5 parser when available. No code changes needed on your end. The native parser is faster and more spec-compliant than the previous fallback. On PHP 8.2 or 8.3 nothing changes.

Translation: StaticMessage

StaticMessage implements TranslatableInterface but intentionally doesn’t translate. It passes the string through unchanged regardless of locale. The use case is API responses that must stay in a fixed language regardless of the user’s locale, or audit log entries where you need to preserve the original text as-is.

The pipe operator

Functional pipelines in PHP have always been a mess. Chaining transformations meant either nesting function calls inside out, or breaking them into intermediate variables:

// before — read right to left
$result = array_sum(array_map('strlen', array_filter($strings, 'strlen')));

// or verbose but readable
$filtered   = array_filter($strings, 'strlen');
$lengths    = array_map('strlen', $filtered);
$result     = array_sum($lengths);

// after — read left to right
$result = $strings
    |> array_filter(?, 'strlen')
    |> array_map('strlen', ?)
    |> array_sum(?);

The |> operator passes the left-hand value into the right-hand expression. The ? placeholder marks where it goes. Pipelines now read in the order operations happen: left to right, top to bottom.

This pairs well with first-class callables from PHP 8.1. The two features compose nicely:

$result = $input |> trim(...) |> strtolower(...) |> $this->normalize(...);

The URI extension

Handling URIs in PHP has always meant either reaching for a third-party library or cobbling together parse_url() (returns an array, not an object), http_build_query(), and manual string concatenation.

The new Uri extension gives you a proper object-oriented API:

$uri = Uri\Uri::parse('https://example.com/path?query=value#fragment');
$modified = $uri->withPath('/new-path')->withQuery('key=val');
echo $modified; // https://example.com/new-path?key=val#fragment

Immutable value objects, RFC-compliant parsing, modify individual components without parsing and reconstructing the whole string. Long overdue.

#[\NoDiscard]

A new attribute that generates a warning when the return value is ignored:

#[\NoDiscard("Use the returned collection, the original is unchanged")]
public function filter(callable $fn): static { ... }

Useful for immutable methods where ignoring the return value is almost certainly a bug. Common in other languages for years, now in PHP where it belongs.

clone with

Cloning an object with modified properties without using property hooks or a custom with() method:

$updated = clone($point) with { x: 10, y: 20 };

Clean syntax for a pattern readonly objects needed: you clone to “modify” since direct mutation isn’t allowed.

PHP 8.5 has a functional streak. The pipe operator and URI extension together make data transformation code meaningfully easier to read. The language keeps moving in a consistent direction.

Closures in constant expressions

A constraint that’s been baked in since PHP 5: constant expressions (attribute arguments, property defaults, parameter defaults, const declarations) couldn’t contain closures or first-class callables. 8.5 removes that.

#[Validate(fn($v) => $v > 0)]
public int $count = 0;

const NORMALIZER = strtolower(...);

class Config {
    public function __construct(
        public readonly Closure $transform = trim(...),
    ) {}
}

This is the missing piece that makes attributes genuinely expressive for validation and transformation rules. Before 8.5, you had to pass class names or string references to attributes and let the framework look them up. Now the callable lives directly in the attribute.

Attributes on constants

The #[\Deprecated] attribute from 8.4 couldn’t be applied to const declarations. 8.5 adds attribute support for constants generally:

const OLD_LIMIT = 100;

#[\Deprecated('Use RATE_LIMIT instead', since: '3.0')]
const API_TIMEOUT = 30;

const RATE_LIMIT = 60;

ReflectionConstant, a new reflection class in 8.5, exposes getAttributes() so tools can read them. Combined with closures in constant expressions, attributes on constants become a real metadata layer for compile-time values.

#[\Override] extends to properties

PHP 8.3 brought #[\Override] for methods. 8.5 extends it to properties:

class Base {
    public string $name = 'default';
}

class Derived extends Base {
    #[\Override]
    public string $name = 'derived';
}

If the property doesn’t exist in the parent, PHP throws an error. Particularly useful with property hooks from 8.4: you can now signal that a hooked property is intentionally overriding a parent’s.

Static asymmetric visibility

8.4 introduced asymmetric visibility (public private(set)) for instance properties. 8.5 brings that to static properties too:

class Registry {
    public static private(set) array $items = [];

    public static function register(string $key, mixed $value): void {
        self::$items[$key] = $value;
    }
}

echo Registry::$items['foo']; // readable
Registry::$items['bar'] = 1; // Error: cannot write outside class

Straightforward pattern: expose a static collection for reading, block external mutation.

Constructor promotion for final properties

Property promotion in constructors has existed since PHP 8.0. The final modifier on promoted properties was the missing piece, 8.5 adds it:

class ValueObject {
    public function __construct(
        public final readonly string $id,
        public final readonly string $name,
    ) {}
}

A subclass can’t override $id or $name with a property of the same name. The final readonly combination on promoted properties makes value objects as locked down as possible without sealing the whole class.

Casts in constant expressions

Another gap in constant expressions: no type casts. 8.5 allows them:

const PRECISION = (int) 3.7;      // 3
const THRESHOLD = (float) '1.5';  // 1.5
const FLAG = (bool) 1;            // true

Sounds minor until you have configuration constants derived from environment variables that need type coercion right at the declaration.

Fatal errors include backtraces

Before 8.5, a fatal error (out-of-memory, stack overflow, type error in certain contexts) produced a message with no context about where in the code it happened. Finding the cause meant inserting debug logging and reproducing.

8.5 adds stack backtraces to fatal error messages, in the same format as exception backtraces. A new INI directive, fatal_error_backtraces, controls the behavior. It’s on by default.

array_first() and array_last()

PHP has had reset() and end() for accessing the first and last elements of an array since PHP 3. Both mutate the array’s internal pointer (not safe to call on a reference), and they return false for empty arrays in a way that’s indistinguishable from a stored false value.

$values = [10, 20, 30];

$first = array_first($values);  // 10
$last  = array_last($values);   // 30

$first = array_first([]);       // null

The new functions return null for empty arrays, don’t touch the internal pointer, and work on any array expression without needing a variable. reset($this->getItems()) was a deprecation warning waiting to happen.

get_error_handler() and get_exception_handler()

PHP has set_error_handler() and set_exception_handler(). Getting the current handler meant either storing it yourself before setting it, or calling set_error_handler(null) and capturing what came back, which also cleared the handler in the process.

8.5 adds:

$current = get_error_handler();
$current = get_exception_handler();

Handy in middleware chains where you want to wrap the existing handler without losing it, or in tests where you want to verify a handler was actually installed.

IntlListFormatter

Formatting a list with locale-appropriate conjunctions has always needed manual string assembly. 8.5 adds IntlListFormatter:

$formatter = new IntlListFormatter('en_US', IntlListFormatter::TYPE_AND);
echo $formatter->format(['apples', 'oranges', 'pears']);
// "apples, oranges, and pears"

$formatter = new IntlListFormatter('fr_FR', IntlListFormatter::TYPE_OR);
echo $formatter->format(['rouge', 'bleu', 'vert']);
// "rouge, bleu ou vert"

The class wraps ICU’s ListFormatter. Three types: TYPE_AND, TYPE_OR, TYPE_UNITS. Width constants control whether you get “and” or “&”. Oxford comma handling, locale-specific conjunction placement, all handled by ICU.

FILTER_THROW_ON_FAILURE for filter_var()

filter_var() returns false on validation failure, which produces the classic false vs null vs 0 ambiguity when you’re filtering untrusted input. A new flag changes that:

try {
    $email = filter_var($input, FILTER_VALIDATE_EMAIL, FILTER_THROW_ON_FAILURE);
} catch (Filter\FilterFailedException $e) {
    // explicitly invalid, not ambiguously false
}

The Filter\FilterFailedException and Filter\FilterException classes are new in 8.5. The flag can’t be combined with FILTER_NULL_ON_FAILURE: the behaviors are mutually exclusive.

Deprecations that clean up years of technical debt

The backtick operator (`command` as an alias for shell_exec()) is deprecated. It’s an obscure syntax that surprises anyone reading the code and is inconsistent with every other PHP function call.

Non-canonical cast names ((boolean), (integer), (double), (binary)) are deprecated in favor of their short forms: (bool), (int), (float), (string). The long forms have been undocumented for years; 8.5 starts the formal removal.

Semicolon-terminated case statements are deprecated:

// deprecated
switch ($x) {
    case 1;
        break;
}

// correct
switch ($x) {
    case 1:
        break;
}

The semicolon form has been syntactically valid since PHP 4 but nobody uses it on purpose. It’s a typo PHP happened to accept.

__sleep() and __wakeup() are deprecated in favor of __serialize() and __unserialize(), which return and receive arrays and compose correctly with inheritance. The old methods had messy semantics around property visibility.

max_memory_limit caps runaway allocations

A new startup-only INI directive: max_memory_limit. It sets a ceiling that memory_limit can’t exceed at runtime. If a script calls ini_set('memory_limit', '10G') and max_memory_limit is 512M, PHP warns and caps the value.

Useful in shared hosting environments, or anywhere you want to make sure a bug or a malicious payload can’t convince PHP to raise its own limit and eat the whole machine’s RAM.

Opcache is always present

In 8.5, Opcache is always compiled into the PHP binary and always loaded. The old situation (Opcache as a loadable extension that might or might not be present depending on build configuration) is gone.

You can still disable it: opcache.enable=0 works fine. What changes is the guarantee that the Opcache API (opcache_get_status(), opcache_invalidate(), etc.) is always available, regardless of how PHP was compiled. Any code that checks extension_loaded('opcache') before calling Opcache functions can drop the check.

JSON streamer for large collections

The default Symfony serializer builds the full response in memory before writing it to the output. For a collection of 10,000 items, this means allocating a PHP array, serializing it to a string, and keeping both in memory until the response is flushed. At scale, this is the source of the OOM errors that force people to add pagination everywhere.

4.2 adds a streaming JSON encoder that writes the response incrementally:

api_platform:
    serializer:
        enable_json_streamer: true

With streaming enabled, the response is written directly to the output buffer as each item is serialized. Memory usage stays roughly constant regardless of collection size. The trade-off: you cannot set response headers after streaming starts, and the HTTP status code must be committed before the first byte is written.

ObjectMapper replaces manual DTO wiring

3.1 introduced stateOptions with DoctrineOrmOptions for separating the API resource from the Doctrine entity. The provider received entity objects and the serializer mapped them to the DTO. This worked, but the mapping was implicit — the serializer used property names to match fields, and anything that did not match was either ignored or caused a normalization error.

4.2 introduces ObjectMapper, a declarative mapping layer between entities and DTOs:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

The #[Map] attribute tells ObjectMapper that BookDto can be populated from BookEntity. Field names are matched by convention; mismatches are declared explicitly at the property level:

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

The dot notation traverses nested objects. The mapping runs before serialization and replaces the implicit property-matching behavior of the serializer. Unmapped fields raise an error at configuration time, not at runtime.

ObjectMapper works with stateOptions:

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

The provider fetches BookEntity objects from Doctrine. ObjectMapper converts them to BookDto instances. The serializer writes the DTO. Three distinct steps, each with a clear contract.

TypeInfo integration throughout the stack

Symfony 7.1 introduced the TypeInfo component , a unified type introspection layer that understands union types, intersection types, generic collections, and nullable types across reflection, PHPDoc, and PHP 8.x syntax.

4.2 replaces API Platform’s internal type resolution with TypeInfo. This affects filter schema generation, OpenAPI schema inference, and the serializer’s type coercion. The visible benefit is that types that previously generated incorrect or missing OpenAPI schemas — Collection<int, Book>, list<string>, intersection types — now produce accurate schemas without manual @ApiProperty annotations.

Autoconfigure #[ApiResource]

Before 4.2, adding #[ApiResource] to a class was sufficient for Hugo to discover it only if the class was in a path scanned by API Platform’s resource loader. Outside that path, you needed explicit service configuration.

4.2 hooks into Symfony’s autoconfigure system. Any class tagged with #[ApiResource] is automatically registered as a resource regardless of its location, as long as it is in a directory covered by Symfony’s component scan. No config/services.yaml entry needed.

For Laravel, the equivalent uses Laravel’s service provider autoloading — Eloquent models with #[ApiResource] are picked up automatically without manual registration.

Doctrine ExistsFilter

The ExistsFilter constrains a collection by whether a nullable relation or field is set:

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true returns books where publishedAt is not null. exists[publishedAt]=false returns books where it is null.

Then you migrate to the cloud. The institutional knowledge doesn’t follow. The SSH access is gone or inconvenient. And for the first time, you’re staring at fourteen FrankenPHP containers with no idea what they’re actually doing.

That’s the moment you need metrics. Not eventually. Before the migration is done.

The problem with doing it properly

The correct way to instrument a PHP service for Prometheus: add a client library, write counters and histograms around what you care about, expose a /metrics route, update the scrape config. For one service, that’s a reasonable afternoon. For fourteen services mid-migration, it’s a multi-sprint project that competes with everything else that needs to move.

The calculation is awkward. You need metrics to trust that the migration is going well. But adding metrics to everything before the migration means the migration takes longer. And the longer it takes, the more you need metrics to know where you stand.

Something had to give.

What FrankenPHP carries without announcing it

FrankenPHP is not a PHP runtime that happens to use Caddy as its web server. The relationship is inverted: Caddy is the server, and PHP is a Caddy module. Every HTTP request flows through Caddy before it reaches application code.

Caddy ships with a Prometheus-compatible metrics endpoint built in. No plugin, no extra binary. Enable the admin API and it’s there.

CADDY_GLOBAL_OPTIONS is a FrankenPHP environment variable that injects directives directly into Caddy’s global configuration block. Two lines are enough:

environment:
    CADDY_GLOBAL_OPTIONS: |
        admin 0.0.0.0:2019
        metrics

admin 0.0.0.0:2019 binds the admin API to all network interfaces - the default is localhost-only, which is unreachable from a Prometheus container on the same network. metrics enables the endpoint.

After that, every container responds to GET :2019/metrics with a full Prometheus payload. Request counts labeled by status code, latency histograms, active connections. No route added to the application. No composer require. No Dockerfile change.

One environment variable, added to each service definition in a single commit. Fourteen scrape targets, all producing data.

A usable picture in Grafana

The Prometheus scrape config lists every service by its container name:

scrape_configs:
    - job_name: caddy
      metrics_path: /metrics
      static_configs:
          - targets:
              - authentication:2019
              - content:2019
              - media:2019
              # all 14 services

Grafana sits on top of Prometheus. The Caddy community dashboard gives you request rates, error rates, and latency percentiles per service, per endpoint, per status code. Within a day of the migration landing in the new environment, there was something meaningful to look at.

The data tier follows the same logic: exporters for PostgreSQL, Redis, and RabbitMQ scrape at the infrastructure level without touching application code. Community dashboards exist for all of them.

What this baseline actually covers

The HTTP metrics from Caddy are web server metrics, not application metrics. They answer: is this service receiving traffic, is it returning errors, how fast is it responding. The kind of questions you ask when something is broken and you need to triage in the dark.

They don’t answer: how many items were processed today, which background job is stuck, what is the business impact of this latency spike. For those you need application instrumentation, and that work still exists when you have specific things to measure.

But in a migration context, that distinction matters less than it sounds. The things that break during a cloud migration are mostly infrastructure problems: a service that can’t reach its database, a memory limit that was set too low, a queue consumer that stopped picking up messages. Those are exactly the things the baseline covers.

Getting instrumentation right for business-level events can wait until the platform is stable. Getting enough visibility to know whether the migration succeeded cannot.

Then in March 2025, Let’s Encrypt revoked the certificate. The wildcard cert for traefik.me is gone and it’s not coming back.

What traefik.me was actually selling

traefik.me is a wildcard DNS resolver. Type anything.traefik.me and it resolves to 127.0.0.1. Type anything.10.0.0.1.traefik.me and it resolves to 10.0.0.1. No account, no configuration, no infrastructure to maintain. The DNS part still works fine, by the way.

The certificate was the bonus: a wildcard cert for *.traefik.me that pyrou, the maintainer, generated with Let’s Encrypt and distributed at https://traefik.me/cert.pem and https://traefik.me/privkey.pem. It was convenient precisely because it was shared: download, drop into Traefik, done.

Sharing a private key is why it died.

The CA/Browser Forum Baseline Requirements, section 9.6.3, require subscribers to “maintain sole control” over their private key. Distributing it to anyone who visits a URL is the exact opposite of sole control. Let’s Encrypt sent a notice, blocked future issuance for the domain, and revoked the existing certificate. Pyrou confirmed the situation and recommended mkcert as an alternative. The project will live on as a DNS resolver only.

The cert had already been revoked twice before 2025. Third time was the last.

sslip.io does the same thing, differently

sslip.io is also a wildcard DNS resolver, with one difference: the IP is encoded in the hostname rather than resolved from a fallback. 10-0-0-1.sslip.io resolves to 10.0.0.1. myapp.192-168-1-10.sslip.io resolves to 192.168.1.10. IPv6 works too.

The infrastructure behind sslip.io is also more visible: three nameservers in Singapore, the US, and Poland, handling over 10,000 requests per second, with public monitoring. About 1,000 GitHub stars and active maintenance under the Apache 2.0 licence.

Strip away the certificate story and the comparison is pretty straightforward:

traefik.me’s only remaining advantage is the 127.0.0.1 fallback: URLs without an IP segment. That matters if you really want myapp.traefik.me instead of myapp.127-0-0-1.sslip.io. Whether that difference is worth the infrastructure uncertainty is a short conversation.

mkcert fills the gap

mkcert creates a local certificate authority, installs it in the system trust store and whatever browsers it finds, then issues certificates signed by that CA. Browsers see a trusted chain. No warning, no click-through, no “proceed anyway”.

mkcert -install

That’s the one-time setup. After that, generating a certificate is one command:

mkcert "*.127-0-0-1.sslip.io"
# produces _wildcard.127-0-0-1.sslip.io.pem
#          _wildcard.127-0-0-1.sslip.io-key.pem

The limitation is that mkcert’s CA is local. Other machines on the network won’t trust it by default. For a solo dev setup that’s fine. For a shared team environment, you’d need to distribute the CA root, which is essentially the same operational problem traefik.me was trying to avoid, just smaller in scope.

The Traefik configuration

The setup is the same regardless of which DNS service you pick. Traefik needs the certificate mounted as a volume and a static file provider pointing at a TLS configuration file.

# traefik/config/tls.yml
tls:
  certificates:
    - certFile: /certs/cert.pem
      keyFile: /certs/key.pem
  stores:
    default:
      defaultCertificate:
        certFile: /certs/cert.pem
        keyFile: /certs/key.pem

The key practice: run Traefik in its own Compose project, separate from the services it routes to. Each service project connects to Traefik through a shared external network. Start and stop services independently without touching the reverse proxy.

Start by creating the external network once:

docker network create traefik-public

traefik/compose.yml - Traefik alone, owning the network:

services:
  traefik:
    image: traefik:v3
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/etc/traefik/config
      - ./certs:/certs
    command:
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --providers.docker=true
      - --providers.docker.network=traefik-public
      - --providers.file.directory=/etc/traefik/config
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

Copy the mkcert output into ./certs/, rename to cert.pem and key.pem, then:

docker compose -f traefik/compose.yml up -d

Traefik is up, listening on 80 and 443, watching Docker for new containers. Nothing is routed yet.

whoami/compose.yml - a service that joins the same network:

services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.127-0-0-1.sslip.io`)"
      - "traefik.http.routers.whoami.tls=true"
      - "traefik.http.routers.whoami.entrypoints=websecure"
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

docker compose -f whoami/compose.yml up -d

Traefik detects the new container via the Docker provider, reads its labels, and adds the route. https://whoami.127-0-0-1.sslip.io responds immediately. Bring whoami down and the route disappears. Traefik keeps running without noticing.

The external: true declaration is the load-bearing line. Without it, Compose creates a project-scoped network: Traefik and whoami end up on different networks and can’t reach each other, even though both are running. The external network is the shared bus every service project must explicitly opt into.

If you prefer traefik.me URLs, replace the mkcert command and the host label:

mkcert "*.traefik.me"

- "traefik.http.routers.whoami.rule=Host(`whoami.traefik.me`)"

The DNS fallback to 127.0.0.1 handles the rest.

What the traefik.me story actually teaches

The certificate distribution model was always fragile. A “public-private key pair” is a contradiction in terms. Every revocation was a warning that the next one could be permanent. Eventually it was.

The lesson isn’t specific to traefik.me. Any service that provides convenience by quietly removing a security boundary will eventually hit that boundary. mkcert is the right tool for this problem because it operates entirely within your own trust domain: you generate the CA, you install it, you issue the certificates. Nothing depends on a third party’s continued willingness to bend certificate issuance rules.

sslip.io solves the DNS part cleanly. mkcert solves the TLS part cleanly. They compose well. The traefik.me setup was simpler, for a while. Until it wasn’t.

Strict query parameter validation

3.3 introduced query parameter validation as opt-in. 3.4 deprecated the loose behavior. 4.1 formalizes it with a native strictQueryParameterValidation property on resources and operations: when set to true, unknown query parameters return 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Declared parameters pass through; undeclared parameters are rejected. To disable strict validation on a specific operation when it is enabled at the resource level, set strictQueryParameterValidation: false on that operation.

x-apiplatform-tag for multi-spec OpenAPI

Large APIs often need multiple OpenAPI specs: one per team, one per API version, one internal and one public. Before 4.1, the generated spec was one document, and splitting it required post-processing or separate API Platform instances.

4.1 adds an x-apiplatform-tag vendor extension (no trailing s). You tag operations with logical group names via the extensionProperties of an OpenAPI Operation object, then request the spec filtered to one or more groups:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Requesting /api/docs.json?filter_tags[]=public returns only the operations tagged public. The full spec is still available without a filter. Groups do not affect the actual API behavior — they are a documentation-layer concern only.

This makes it feasible to maintain one API Platform configuration while serving different spec views to different consumers: a public Swagger UI, a partner portal, and an internal tool that exposes admin endpoints.

HTTP authentication in Swagger UI

Before 4.1, the Swagger UI bundled with API Platform supported Bearer token authentication via its “Authorize” dialog. API Key and HTTP Basic authentication were not wired in.

4.1 adds support for multiple security schemes in the generated OpenAPI document. Security schemes are added by decorating the OpenApiFactory and modifying the components.securitySchemes object of the spec. Each declared scheme then appears in Swagger UI’s “Authorize” dialog and is applied to requests made from the UI. This is a documentation and developer experience improvement — the actual authentication logic in your application is not affected.

GraphQL query depth and complexity limits

GraphQL’s recursive query structure makes it trivial to craft a query that is small in bytes but enormous in execution cost. Without limits, a nested query four levels deep across a many-to-many relation can hit the database hundreds of times.

4.1 adds configurable depth and complexity limits:

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth is the maximum nesting level. max_query_complexity assigns a cost to each field and rejects queries whose total cost exceeds the threshold. Queries that exceed either limit are rejected before execution with a 400 response.

There is no universally correct value for these limits — they depend on your schema shape and expected query patterns. The defaults are intentionally permissive to avoid breaking existing APIs on upgrade. Tightening them is a deliberate configuration choice.

Operation-level output formats

4.0 and earlier configured accepted and returned content types at the API level. 4.1 lets you narrow this per operation:

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Operations that do not specify formats inherit the API-level configuration. This is useful for endpoints that need to return a specific format (a CSV export, a binary stream) without changing the defaults for the rest of the API.

PostgreSQL has had built-in full-text search for over fifteen years. The platform was already on PostgreSQL. The catch: the project uses Doctrine ORM, and Doctrine doesn’t natively know what a tsvector is.

A community library, postgresql-for-doctrine, covers part of that gap. It registers basic DQL functions like TO_TSQUERY, TO_TSVECTOR, and the @@ match operator as separate atomic pieces. The foundation was there. Three things still had to be built on top.

The type Doctrine has never seen

PostgreSQL’s full-text search is built around two types: tsvector (a pre-processed list of normalized tokens) and tsquery (a search expression). You maintain a tsvector column, index it with GIN, and query with the @@ match operator.

Doctrine’s DBAL ships no tsvector type. Declaring #[ORM\Column(type: 'tsvector')] without registering it first throws a UnknownColumnTypeException. The fix is a custom DBAL type:

class TsVector extends Type
{
    final public const string DBAL_TYPE = 'tsvector';

    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string
    {
        return self::DBAL_TYPE;
    }

    public function getName(): string
    {
        return self::DBAL_TYPE;
    }

    public function convertToDatabaseValueSQL(string $sqlExpr, AbstractPlatform $platform): string
    {
        return sprintf("to_tsvector('simple', %s)", $sqlExpr);
    }

    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
    {
        if (is_array($value) && isset($value['data'])) {
            return $value['data'];
        }

        return is_string($value) ? $value : null;
    }

    public function getMappedDatabaseTypes(AbstractPlatform $platform): array
    {
        return [self::DBAL_TYPE];
    }
}

The interesting method is convertToDatabaseValueSQL(). Doctrine calls it to wrap the SQL placeholder before the value reaches the database. The written value automatically becomes to_tsvector('simple', ?) at the DBAL boundary with no extra step needed on the calling side.

Register the type in doctrine.yaml, then map the column on the entity:

doctrine:
    dbal:
        types:
            tsvector: App\Doctrine\DBAL\Types\TsVector

#[ORM\Column(type: 'tsvector', nullable: true)]
protected ?string $textSearch = null;

PHP-side, the value is a plain string. The conversion to a proper tsvector happens invisibly at the DBAL layer.

We used the 'simple' dictionary, which tokenizes on whitespace and punctuation without language-specific stemming. The platform handles multiple languages, and French stemming rules would break Spanish. Simple is good enough for phonetics.

Keeping the column current

A tsvector column is derived data: it has to stay in sync with the source fields whenever the entity changes. A Doctrine event listener handles that:

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class MediaTsVectorSubscriber
{
    public function prePersist(PrePersistEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    public function preUpdate(PreUpdateEventArgs $event): void
    {
        if (!$event->getObject() instanceof Media) {
            return;
        }
        $this->updateTextSearch($event->getObject());
    }

    private function updateTextSearch(Media $entity): void
    {
        $entity->setTextSearch(
            sprintf('%s %s', $entity->getTitle(), $entity->getCaption())
        );
    }
}

Before every persist and update, the subscriber concatenates the fields that should be searchable into textSearch. Doctrine flushes the combined string, the DBAL type wraps it in to_tsvector('simple', ...), and PostgreSQL stores the tokenized form.

One subtlety: the PHP-side value is "title caption", not the actual tsvector output. The database shows 'caption' 'title' (sorted tokens), but the entity holds a plain string. That’s expected: the conversion is a DBAL responsibility, not a PHP one. It can be confusing to debug until you remember where the boundary is.

Extending DQL with FTS operators

Doctrine’s DQL covers common SQL operations, but anything PostgreSQL-specific is out of scope. That’s where postgresql-for-doctrine starts: it registers TO_TSQUERY, TO_TSVECTOR, and TSMATCH as individual DQL functions. Writing a full-text query in DQL without it would mean dropping to native SQL entirely.

The library’s functions are atomic, though. Each maps to one SQL call. Expressing a full match check in DQL looks like TSMATCH(o.textSearch, TO_TSQUERY(:term)). Readable enough, but the team wanted something more compact: a single DQL function that encodes both the match operator and the query type, including websearch_to_tsquery, which postgresql-for-doctrine didn’t ship.

The solution is custom DQL functions via FunctionNode. You parse the DQL syntax, then emit SQL. All FTS functions share the same two-argument signature, so an abstract base class handles parsing:

abstract class TsFunction extends FunctionNode
{
    public PathExpression|Node|null $ftsField = null;
    public PathExpression|Node|null $queryString = null;

    public function parse(Parser $parser): void
    {
        $parser->match(TokenType::T_IDENTIFIER);
        $parser->match(TokenType::T_OPEN_PARENTHESIS);
        $this->ftsField = $parser->StringPrimary();
        $parser->match(TokenType::T_COMMA);
        $this->queryString = $parser->StringPrimary();
        $parser->match(TokenType::T_CLOSE_PARENTHESIS);
    }
}

Each concrete class implements getSql() to emit its PostgreSQL expression:

// e.textSearch @@ websearch_to_tsquery('simple', :term)
class TsWebsearchQueryFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return $this->ftsField->dispatch($sqlWalker)
            ." @@ websearch_to_tsquery('simple', "
            .$this->queryString->dispatch($sqlWalker).')';
    }
}

// ts_rank(e.textSearch, to_tsquery(:term)) for relevance ordering
class TsRankFunction extends TsFunction
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ts_rank('
            .$this->ftsField->dispatch($sqlWalker)
            .', to_tsquery('.$this->queryString->dispatch($sqlWalker).'))';
    }
}

doctrine:
    orm:
        entity_managers:
            default:
                dql:
                    string_functions:
                        tswebsearchquery: App\Doctrine\ORM\Query\AST\Functions\TsWebsearchQueryFunction
                        tsrank: App\Doctrine\ORM\Query\AST\Functions\TsRankFunction
                        tsquery: App\Doctrine\ORM\Query\AST\Functions\TsQueryFunction
                        tsplainquery: App\Doctrine\ORM\Query\AST\Functions\TsPlainQueryFunction

websearch_to_tsquery is the right choice for user-facing search: spaces become AND, quoted strings become phrases, -word excludes a term. No need to teach users to type interview & president. It was added in PostgreSQL 11. On older versions, plainto_tsquery is the closest equivalent.

The API Platform filter and the GIN index

With the DQL functions registered, the API Platform filter is straightforward. A custom AbstractFilter calls the DQL function directly in the QueryBuilder:

class TextSearchFilter extends AbstractFilter
{
    protected function filterProperty(
        string $property,
        $value,
        QueryBuilder $queryBuilder,
        QueryNameGeneratorInterface $queryNameGenerator,
        string $resourceClass,
        ?Operation $operation = null,
        array $context = []
    ): void {
        if ('textSearch' !== $property || empty($value)) {
            return;
        }

        $queryBuilder
            ->andWhere('tswebsearchquery(o.textSearch, :value) = true')
            ->setParameter(':value', $value);
    }

    public function getDescription(string $resourceClass): array
    {
        return [];
    }
}

Apply it on the entity alongside the index declaration:

#[ORM\Index(
    columns: ['text_search'],
    name: 'media_text_search_idx_gin',
    options: ['USING' => 'gin (text_search)']
)]
#[ApiFilter(TextSearchFilter::class, properties: ['textSearch' => 'partial'])]
class Media
{
    // ...
    #[ORM\Column(type: 'tsvector', nullable: true)]
    protected ?string $textSearch = null;
}

The USING gin option is non-negotiable. A standard B-tree index on a tsvector column is useless: PostgreSQL can’t use it for @@ queries. GIN (Generalized Inverted Index) works differently: it indexes each token individually, so lookups by any token are O(log n) rather than O(n). Without it, you’ve built a fast-looking system that still does a full table scan.

A GET /media?textSearch=interview+president now hits the GIN index and returns in single-digit milliseconds regardless of table size.

What the split actually looked like

The library covered the low-level atomic functions. The custom code covered the gaps: a tsvector DBAL type the library didn’t provide, convenience DQL wrappers that combined @@ and websearch_to_tsquery into a single call, and the application-specific glue connecting it all to Doctrine’s event system and API Platform. Nothing needed to drop to a native query.

The split is worth noting in general: postgresql-for-doctrine gives you the atomic PostgreSQL building blocks, but you still need to compose them into something the rest of the codebase can use without thinking about it. The FunctionNode pattern and the convertToDatabaseValueSQL() hook are the two extension points that make that composition clean. Both are worth knowing about, regardless of what library you start from.

Property hooks

For twenty years, if you wanted behavior on property access in PHP you had to write getters and setters:

class User {
    private string $_name;
    
    public function getName(): string { return $this->_name; }
    public function setName(string $name): void {
        $this->_name = strtoupper($name);
    }
}

PHP 8.4 adds hooks directly on the property:

class User {
    public string $name {
        set(string $name) {
            $this->name = strtoupper($name);
        }
    }
}

You can define get and set hooks independently. A property with only a get hook is computed on access:

class Circle {
    public float $area {
        get => M_PI * $this->radius ** 2;
    }
    
    public function __construct(public float $radius) {}
}

No backing storage, no explicit getter method, full IDE support. Interfaces can declare properties with hooks too, which means contracts can now specify behavior on property access, something that was flat-out impossible before.

Asymmetric visibility

A lighter option for when you just want public read, private write:

class Version {
    public private(set) string $value = '1.0.0';
}

$v = new Version();
echo $v->value;      // works
$v->value = '2.0';  // Error

Kills the private $x + public getX() pattern for read-only public properties without needing full readonly semantics.

array_find() and friends

$first = array_find($users, fn($u) => $u->isActive());
$any   = array_any($users, fn($u) => $u->isPremium());
$all   = array_all($users, fn($u) => $u->isVerified());

These have been in every other language’s standard library for decades. In PHP, you had to use array_filter() + index access or write a manual loop. They exist now: array_find(), array_find_key(), array_any(), array_all().

Instantiation without extra parentheses

// before
(new MyClass())->method();

// after
new MyClass()->method();

A syntax restriction that was always annoying and never justified is gone.

Lazy objects

Objects whose initialization is deferred until first property access:

$user = $reflector->newLazyProxy(fn() => $repository->find($id));
// No database call yet
$user->name; // Now the proxy initializes

The direct audience is framework ORM and DI container authors, not application developers. But the effect shows up in every app that uses Doctrine or Symfony: lazy loading implemented at the language level rather than through code generation.

PHP 8.4 is a language that barely resembles the PHP 5 most of us started with. Property hooks in particular: they’re not a workaround, they’re a design feature.

#[\Deprecated] for your own code

PHP has emitted deprecation notices for built-in functions for years. 8.4 lets you wire the same mechanism into your own code:

class ApiClient {
    #[\Deprecated(
        message: 'Use fetchJson() instead',
        since: '2.0',
    )]
    public function get(string $url): string { ... }
}

Calling a deprecated method now emits E_USER_DEPRECATED, just like calling mysql_connect(). IDEs pick it up, static analyzers flag it, the error log captures it. Before this, the only option was a @deprecated PHPDoc comment: fine for IDEs, completely invisible to the engine.

BcMath\Number makes arbitrary precision usable

The bcmath functions have been in PHP since forever, but their procedural API makes chaining anything painful. 8.4 adds BcMath\Number, an object wrapper with operator overloading:

$a = new BcMath\Number('10.5');
$b = new BcMath\Number('3.2');

$result = $a + $b;             // BcMath\Number('13.7')
$result = $a * $b - new BcMath\Number('1');
echo $result;                  // 32.6

The +, -, *, /, **, % operators all work. The object is immutable. Scale propagates automatically through operations. Financial calculations, which used to mean chains of bcadd(bcmul(...), ...), now just read like arithmetic.

New procedural functions complete the picture: bcceil(), bcfloor(), bcround(), bcdivmod().

RoundingMode enum replaces PHP_ROUND_* constants

round() has always taken a $mode int from a set of PHP_ROUND_* constants. 8.4 replaces that with a RoundingMode enum with cleaner names and four additional modes that weren’t available before:

round(2.5, mode: RoundingMode::HalfAwayFromZero);  // 3
round(2.5, mode: RoundingMode::HalfTowardsZero);   // 2
round(2.5, mode: RoundingMode::HalfEven);          // 2 (banker's rounding)
round(2.5, mode: RoundingMode::HalfOdd);           // 3

// The four new modes (only available via the enum)
round(2.3, mode: RoundingMode::TowardsZero);       // 2
round(2.7, mode: RoundingMode::AwayFromZero);      // 3
round(2.3, mode: RoundingMode::PositiveInfinity);  // 3
round(2.3, mode: RoundingMode::NegativeInfinity);  // 2

The old PHP_ROUND_* constants still work. The enum is the path forward.

Multibyte string functions that should have existed

mb_trim(), mb_ltrim(), mb_rtrim(): trim functions that respect multibyte character boundaries, not just ASCII whitespace. Also new: mb_ucfirst() and mb_lcfirst() for proper title-casing of multibyte strings.

$s = "\u{200B}hello\u{200B}"; // Zero-width spaces
echo mb_trim($s);              // "hello"
echo mb_ucfirst('über');       // "Über"

These fill gaps that have been sitting there since mbstring was introduced.

request_parse_body() for non-POST requests

PHP automatically parses application/x-www-form-urlencoded and multipart/form-data into $_POST and $_FILES, but only for POST requests. PATCH and PUT requests with the same content types needed manual parsing with file_get_contents('php://input') and custom code.

// Inside a PATCH handler
[$_POST, $_FILES] = request_parse_body();

The function returns a tuple. Same parsing logic PHP uses for POST, now available for any HTTP method.

A new DOM API that follows the spec

The existing DOMDocument API was built on an older DOM level 3 spec with PHP-specific quirks layered on top. 8.4 adds a parallel Dom\ namespace that implements the WHATWG Living Standard:

$doc = Dom\HTMLDocument::createFromString('<p class="lead">Hello</p>');
$p = $doc->querySelector('p');
echo $p->classList;  // "lead"
echo $p->id;         // ""

$doc2 = Dom\HTMLDocument::createFromFile('page.html');

Dom\HTMLDocument parses HTML5 correctly, tag soup included. Dom\XMLDocument handles strict XML. The new classes are strict about types, return proper node types, and expose modern properties like classList, id, className. The old DOMDocument stays, unchanged, for backward compatibility.

PDO gets driver-specific subclasses

PDO::connect() and direct instantiation now return driver-specific subclasses when available:

$pdo = PDO::connect('mysql:host=localhost;dbname=test', 'user', 'pass');
// $pdo is now a Pdo\Mysql instance

$pdo = new Pdo\Pgsql('pgsql:host=localhost;dbname=test', 'user', 'pass');

Each driver subclass (Pdo\Mysql, Pdo\Pgsql, Pdo\Sqlite, Pdo\Firebird, Pdo\Odbc, Pdo\DbLib) can expose driver-specific methods without polluting the base PDO interface. Doctrine, Laravel, and similar ORMs can now type-hint against the specific driver class when they need driver-specific behavior.

OpenSSL gets modern key support

openssl_pkey_new() and related functions now support Curve25519 and Curve448, the modern elliptic curves that have replaced older NIST curves in most security recommendations:

$key = openssl_pkey_new(['curve_name' => 'ed25519', 'private_key_type' => OPENSSL_KEYTYPE_EC]);
$details = openssl_pkey_get_details($key);

x25519 and x448 for key exchange, ed25519 and ed448 for signatures. All four now work with openssl_sign() and openssl_verify().

PCRE: variable-length lookbehind

The bundled PCRE2 library update (10.44) brings variable-length lookbehind assertions, something Perl and Python regex engines had and PHP couldn’t do:

// Match "bar" only when preceded by "foo" or "foooo"
preg_match('/(?<=foo+)bar/', 'foooobar', $matches);

Lookbehind assertions used to require a fixed-width pattern. Now they can match patterns of variable length. The r modifier (PCRE2_EXTRA_CASELESS_RESTRICT) is also new: it prevents mixing ASCII and non-ASCII characters in case-insensitive matches, closing a class of Unicode confusion attacks.

DateTime gets microseconds and timestamp factory

$dt = DateTimeImmutable::createFromTimestamp(1700000000.5);
echo $dt->getMicrosecond(); // 500000

$with_micros = $dt->setMicrosecond(123456);

createFromTimestamp() accepts a float for sub-second precision. getMicrosecond() and setMicrosecond() round out the API for the microsecond component that’s been inside DateTime internally but inaccessible directly.

fpow() for IEEE 754 compliance

pow(0, -2) in PHP has historically returned an implementation-defined value. 8.4 deprecates pow() with a zero base and negative exponent and introduces fpow(), which strictly follows IEEE 754: fpow(0, -2) returns INF, as the standard defines:

echo fpow(2.0, 3.0);   // 8.0
echo fpow(0.0, -1.0);  // INF
echo fpow(-1.0, INF);  // 1.0

Worth knowing in any code doing mathematical computations where IEEE compliance matters.

The cost of bcrypt goes up

The default cost for password_hash() with PASSWORD_BCRYPT went from 10 to 12. This hits any code calling password_hash($pass, PASSWORD_BCRYPT) without an explicit cost. The goal is to keep the default roughly “a few hundred milliseconds on modern hardware” as hardware gets faster.

If you store bcrypt hashes and upgrade to 8.4, existing hashes stay valid: password_verify() reads the cost from the hash itself. New hashes use cost 12. password_needs_rehash() returns true for old hashes if you pass ['cost' => 12], so you can upgrade them on next login.

Deprecations that matter

Implicitly nullable parameters are deprecated. If a parameter has a default of null, the type has to say so explicitly:

// Deprecated in 8.4
function foo(string $s = null) {}

// Correct
function foo(?string $s = null) {}
function foo(string|null $s = null) {}

trigger_error() with E_USER_ERROR is deprecated: replace it with an exception or exit(). The E_USER_ERROR level was always an awkward hybrid between a recoverable error and a fatal one, and nobody was sure which.

lcg_value() is deprecated too. Use Random\Randomizer::getFloat() instead. The LCG generator had poor randomness properties and no seeding control.

Laravel as a first-class target

Since its first release, API Platform was built on Symfony. The HTTP layer, metadata, serializer, and Doctrine bridge all assumed Symfony’s container, event dispatcher, and request lifecycle. Laravel users could run API Platform through a thin adapter, but filters, security, and Doctrine integration did not work on Eloquent.

4.0 ships a dedicated Laravel bridge. It maps API Platform’s state layer onto Laravel’s request lifecycle, integrates with Eloquent models directly, and wires into Laravel’s authorization system:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

Authorization uses Laravel policies and gates rather than Symfony’s security voters. Operations expose a dedicated policy parameter that maps to a policy method name:

#[Get(policy: 'view')]
class Book extends Model {}

API Platform maps the policy value to Laravel’s Gate::allows() with the model instance. Policies can also be auto-detected: if a model has a registered policy class, API Platform infers the correct method (view, viewAny, create, update, delete) based on the operation type. Filters for Eloquent collections cover the same ground as their Doctrine counterparts: PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, and search variants (StartSearchFilter, EndSearchFilter). Pagination, sorting, and validation work through Laravel’s native mechanisms.

This is not a compatibility shim. The Laravel bridge is maintained alongside the Symfony bridge and is covered by the same test suite. Projects using either framework get the same resource definition API.

PUT removed from default operations

Since API Platform 1.0, #[ApiResource] without an explicit operations array generated CRUD operations including PUT. The PUT handler updated existing resources and, after 3.1, could also create them via allowCreate: true.

4.0 removes PUT from the default set. #[ApiResource] now generates GET, POST, PATCH, and DELETE. To use PUT, you must declare it explicitly:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... other operations
        new Put(),
    ]
)]
class Book {}

The motivation is semantic clarity. PATCH replaces PUT for most partial-update use cases. PUT’s semantics — replace the entire resource representation — are rarely what an API actually implements, but the default made it appear in every API unless actively removed. Making PUT opt-in aligns the defaults with how HTTP semantics are actually used in practice.

PHP 8.2 minimum

4.0 drops PHP 8.0 and 8.1. PHP 8.2 is the new minimum. The readonly class syntax, AllowDynamicProperties, and DNF¹ types introduced in 8.2 are available throughout the codebase. No specific 8.2 feature is load-bearing for 4.0 — the version bump is primarily about dropping the older maintenance burden.

Symfony 6.4+ and Doctrine ORM 2.17+ minimum

On the Symfony side, 4.0 requires Symfony 6.4 or 7.x and Doctrine ORM 2.17 or 3.x. Both were already supported in 3.4. The migration from 3.4 to 4.0 on the Symfony track is: resolve 3.4 deprecations, verify you are on Symfony 6.4+ and ORM 2.17+, then upgrade. No new migration work is required if those are already in place.

What 4.0 is not

4.0 is not a new architecture. The state providers, processors, and resource metadata model from 3.0 are unchanged. The Laravel bridge adds a new execution context but does not change how resources or operations are declared. The split is intentional: if 3.0 was the “what”, 4.0 is the “where”.

BackedEnum as API resources

Since PHP 8.1, BackedEnum classes have a fixed set of cases with string or integer backing values. API Platform 3.4 lets you put #[ApiResource] directly on a BackedEnum:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

A GET /book_statuses endpoint returns the list of cases. Each case is serialized with its name and value. The endpoint is read-only — enums are immutable by nature.

This is mostly useful for frontend consumers that want a machine-readable list of valid values without hardcoding them. The alternative was a custom controller or a dedicated DTO resource listing the enum values manually.

BackedEnumFilter

The companion to enum resources is BackedEnumFilter, a new filter for Doctrine collections that constrains a query by a BackedEnum property:

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filters the collection to books where status equals BookStatus::Published. Invalid enum values return a 400 response. Before this filter, you had to either write a custom filter or use SearchFilter and validate the value manually.

Security expressions on parameters

3.3 added security to links and properties. 3.4 extends this to query parameters. A parameter can declare a security expression that controls whether it is accepted at all:

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

When the security expression is false, the parameter is rejected with a 403, not silently ignored. This is more explicit than checking the user’s role inside the provider after receiving the parameter.

DBAL 4 support added

3.4 adds support for Doctrine DBAL 4, which ships with type system changes that affect how custom types and platform-specific SQL work. The Doctrine Orm filters and query extensions in API Platform were updated to work with the new DBAL 4 type API.

Both DBAL 3 (^3.4.0) and DBAL 4 are supported simultaneously in 3.4. This is the release to upgrade to if you want to adopt DBAL 4 while staying on a stable API Platform 3.x branch.

Query parameter validator deprecated

3.3 added the strict query parameter validator as an opt-in. 3.4 deprecates the old behavior (unknown parameters silently ignored) in preparation for making strict validation the default in 4.0. Projects that relied on pass-through query parameters have one more release to declare them explicitly.

Last stop before 4.0

3.4 is the last 3.x release with new features. Anything 3.x that was deprecated by 3.4 is gone in 4.0. The migration path from 3.4 to 4.0 is intentionally short: resolve the deprecations, then upgrade.

Declarative header configuration

Before 3.3, setting custom response headers required either a custom processor that modified the response object or a Symfony event listener on kernel.response. Both approaches worked but lived outside the resource definition.

3.3 adds a parameters parameter to operation metadata:

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

For headers that vary per response (like Cache-Control with a computed max-age), the processor can still set them directly on the response. The headers parameter is primarily for documenting expected headers in the OpenAPI spec and for static header values.

Link security on sub-resources

When a resource exposes links to related resources, those links appear in the serialized output regardless of whether the current user can access the linked resource. This creates a disclosure problem: a user who can read a book but not its author profile still sees the author’s URI in the response.

3.3 adds security expressions to the Link descriptor:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

The link is omitted from the response when the security expression evaluates to false. The linked resource itself is not affected — only whether the current response includes the reference to it.

ApiProperty::security

The same security expression mechanism is available at the property level via ApiProperty::security. This lets you hide individual fields based on the current user without writing a custom normalizer:

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

The property is excluded from serialization when the expression is false. This is cleaner than a normalizer for the common case of role-gated fields.

OpenAPI webhooks

OpenAPI 3.1 supports webhooks — outbound HTTP calls that your API makes to registered listeners — in the spec document itself. Before 3.3, there was no way to document these in API Platform’s generated spec.

3.3 adds a Webhook class you pass to the openapi parameter of an operation. Declare a dedicated PHP class with #[ApiResource] and use Webhook on each operation to describe the outbound call shape:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'A book was created'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

The webhook definitions appear in the generated spec under the webhooks key alongside regular paths. Swagger UI renders them in a separate section.

Swagger UI deep linking

Swagger UI supports deep linking — bookmarkable URLs that open directly to a specific operation in the interface. Before 3.3, the API Platform integration did not enable this. 3.3 turns on the Swagger UI deepLinking option, configurable via swagger_ui_extra_configuration:

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

With this enabled, the URL fragment updates as you navigate the UI, and pasting or sharing the URL opens the same operation. Useful when writing docs that link directly to a specific endpoint.

Strict query parameter validation

3.3 tightens the query parameter validator: parameters not declared on the operation now return a 400 response instead of being silently ignored. This behavior is opt-in:

api_platform:
    validator:
        query_parameter_validation: true

The intent is to catch typos and API misuse early. If you rely on pass-through query parameters for custom logic (logging, feature flags), you need to declare them explicitly on the operation before enabling this.

The most visible removal: Doctrine annotations. @Route, @ORM\Column, @Assert - gone. Native PHP attributes have been the recommended approach since Symfony 5.2. 7.0 just makes it official.

Attributes everywhere

The migration from annotations to attributes is mostly mechanical: syntax changes from @ to #[], and the class references move from Doctrine annotation classes to PHP attribute classes:

// before
/** @Route('/users', methods={"GET"}) */

// after
#[Route('/users', methods: ['GET'])]

The real win isn’t just the syntax: attributes are validated by the PHP engine, not a docblock parser. IDEs can resolve them without custom plugins. Static analysis tools understand them natively. No more “it fails silently at runtime because of a typo in a comment.”

Workflow with PHP attributes

Workflow event listeners and guards can now be registered via attributes:

#[AsGuard(workflow: 'order', transition: 'ship')]
public function canShip(Event $event): void
{
    if (!$event->getSubject()->isPaymentConfirmed()) {
        $event->setBlocked(true);
    }
}

The workflow profiler, a dedicated panel showing the current marking and available transitions, is a genuinely useful debugging tool if you’re working with complex state machines.

:clock1: DatePoint in the Clock component

DatePoint, the immutable DateTime with strict error handling introduced in 6.4, is now the recommended way to work with dates. Combine it with PHP 8.2’s readonly properties and date value objects in domain code become almost trivially clean:

readonly class Order {
    public function __construct(
        public DatePoint $createdAt,
        public ?DatePoint $shippedAt = null,
    ) {}
}

What 7.0 removes

The full removal list: Doctrine annotations support, the Templating component bridge, ProxyManager bridge, the Monolog bridge for versions below 3.0, and the Sendinblue transport (replaced by Brevo). PHP 8.0 and 8.1 support also ends. 8.2 is the floor now.

Upgrade from 6.4 with all deprecation notices fixed, and 7.0 is smooth. Skip that step and you’re in for a bad time.

Scheduler and AssetMapper graduate

Two components that shipped as experimental in 6.3 are now stable: Scheduler and AssetMapper. Stable means locked APIs, no more @experimental caveats, and they show up properly in the upgrade guide. You can actually rely on them now.

Scheduler gets #[AsCronTask] and #[AsPeriodicTask] for attribute-based task registration, runtime schedule modification with heap recalculation, FailureEvent, and a --date option on schedule:debug. AssetMapper adds CSS file support in importmap, an outdated command, an audit command, and automatic preloading via WebLink.

#[AsCronTask('0 2 * * *')]
class NightlyReportMessage {}

#[AsPeriodicTask(frequency: '1 hour')]
class HourlyCleanupMessage {}

Service wiring gets two new attributes

#[AutowireLocator] and #[AutowireIterator] landed in 6.4 and graduate to stable in 7.0. They replace the verbose XML/YAML tagged service locator config with something you can just put directly in PHP:

class HandlerRegistry
{
    public function __construct(
        #[AutowireLocator('app.handler', indexAttribute: 'key')]
        private ContainerInterface $handlers,
    ) {}
}

#[Target] also gets smarter: when a service has a named autowiring alias like invoice.lock.factory, you can now write #[Target('invoice')] instead of the full alias name. Less noise when the type already tells you what you want.

Messenger gets more precise failure handling

RejectRedeliveredMessageException tells the worker to not retry a message, which is handy when a message arrives twice because of a transport ack timeout and you need exactly-once semantics. messenger:failed:remove --all clears the entire failure transport in one shot, no loop required. Failed retries can also go directly to the failure transport, bypassing the retry queue entirely.

Multiple Redis Sentinel hosts are now supported in the DSN:

redis-sentinel://host1:26379,host2:26379,host3:26379/mymaster

Console gets signal names and command profiling

SignalMap maps signal integers to their POSIX names. When a worker catches SIGTERM, the log now says SIGTERM instead of 15. Small thing, real improvement. ConsoleTerminateEvent is dispatched even when the process exits via signal, which wasn’t the case before 7.0.

Command profiling lands too: pass --profile to bin/console and the collected data goes straight into the Symfony profiler, browsable from the web UI.

Form: small things that add up

ChoiceType gets a duplicate_preferred_choices option. Set it to false and you stop showing the same option twice when preferred choices overlap with the full list. FormEvent::setData() is deprecated for events where the data is already locked at that point in the lifecycle. The self-closing slash on <input> elements is also gone: <input> is a void element in HTML5 and the slash was technically invalid.

Enum support in forms is a nice one: ChoiceType renders backed enums directly, and translatable enums get their labels through the translator without any custom wiring.

HttpFoundation: small but useful

Response::send() gets a $flush parameter. Pass false to buffer the output without flushing to the client, useful when chaining middleware that needs to inspect the response before it leaves the process.

UriSigner moves from HttpKernel to HttpFoundation, where it belongs semantically. Same class name, different namespace.

Cookies get CHIPS support (Cookies Having Independent Partitioned State), the browser mechanism for cross-site cookies in a first-party partition. Only matters if you build embeddable widgets, but good to know it’s there.

Translation: Phrase provider and tree output

Phrase joins Crowdin and Lokalise as a supported translation provider. Configure it in config/packages/translation.yaml and the translation:push / translation:pull commands handle the sync.

translation:pull gets an --as-tree option that writes translation files in nested YAML rather than flat dot-notation keys. Whether that’s actually better depends entirely on your team.

LocaleSwitcher::runWithLocale() now passes the current locale as an argument to the callback, saving you a getLocale() call inside:

$switcher->runWithLocale('fr', function (string $locale) use ($mailer) {
    $mailer->send($this->buildEmail($locale));
});

A few things in Serializer and DomCrawler

The Serializer’s Context attribute can now target specific classes, so a single DTO can behave differently during (de)serialization depending on which class holds the context. TranslatableNormalizer lands for normalizing objects that implement TranslatableInterface: the translator is called during normalization, not before.

Crawler::attr() gains a $default parameter. Instead of null-checking the return value, pass a fallback:

$src = $crawler->attr('src', '/placeholder.png');

assertAnySelectorText() and assertAnySelectorTextContains() join the DomCrawler assertion set. They pass if at least one matching element satisfies the condition, rather than requiring all of them to match.

HttpClient: HAR responses for testing

MockResponse now accepts HAR (HTTP Archive) files. Record real HTTP interactions in your browser or with a proxy, drop the .har file in your test fixtures, and replay them:

$client = new MockHttpClient(HarFileResponseFactory::createFromFile(__DIR__.'/fixtures/api.har'));

Much better than writing response stubs by hand when you’re dealing with a complex API.

AssetMapper

Modern frontend tooling in Symfony meant Webpack Encore. Encore works: it handles transpilation, bundling, versioning, hot reload. It also requires Node.js, a separate build step, and a non-trivial amount of configuration for what is often a pretty modest frontend.

AssetMapper takes a different position. Modern browsers support ES modules natively. Instead of bundling, ship the files as-is, let the browser resolve imports through an importmap, and manage vendor dependencies through downloaded files rather than npm packages.

composer require symfony/asset-mapper
php bin/console importmap:require lodash

No Node.js. No npm. No build step. JavaScript and CSS files are versioned and served directly, with a digest in the URL for cache busting. For apps where the frontend is not the primary engineering concern, this removes an entire toolchain from the equation.

6.4 adds CSS files to the importmap, automatic CSS preloading via WebLink, and commands to audit and update vendor dependencies. The package.json experience, minus npm.

Scheduler

The Scheduler component (periodic and cron-style task scheduling without an external job runner) exits experimental and becomes stable. The API uses attributes:

#[AsCronTask('0 * * * *')]
class HourlyReport implements ScheduledTaskInterface
{
    public function run(): void { ... }
}

Backed by Messenger transports, tasks run in any environment where a worker is running. For many use cases, this replaces the classic cron entry + console command pattern.

Webhook and RemoteEvent

Also graduating from experimental: the Webhook component handles incoming webhooks from external services. Instead of writing raw controllers that parse payloads and dispatch events by hand, you configure parsers for known services (Stripe, GitHub, Mailgun) and get typed events.

:clock3: DatePoint

A new DatePoint class in the Clock component: an immutable DateTime wrapper that throws exceptions on invalid modifiers instead of silently returning false. Small thing, but meaningful for code that manipulates dates and actually wants to know when something goes wrong.

The support window

6.4 LTS gets bug fixes until November 2026 and security fixes until November 2027. The path from 6.4 to 7.4 (the next LTS) runs through the 6.4 deprecation notices, as usual.

Routes without magic strings

FQCN-based route aliases are now generated automatically. If a controller method has a single route, Symfony creates an alias using its fully qualified class name:

// Previously: only 'blog_index' worked
// Now: both work identically
$this->urlGenerator->generate('blog_index');
$this->urlGenerator->generate(BlogController::class.'::index');

For invokable controllers, the alias is just the class name. The practical benefit is IDE navigation and refactoring safety: you’re referencing a class constant, not a string that can silently drift.

Two new DI attributes

#[AutowireLocator] and #[AutowireIterator] join the DI attribute family. Instead of configuring service locators and tagged iterables in YAML, you just declare them on constructor parameters:

public function __construct(
    #[AutowireLocator([FooHandler::class, BarHandler::class])]
    private ContainerInterface $handlers,
) {}

Aliases, optional services (prefixed with ?), and parameter injection via SubscribedService are all supported. The locator lazy-loads, so only the handlers you actually call get instantiated.

Messenger gets built-in handlers

Three new message classes cover common tasks that previously required custom handlers.

RunProcessMessage dispatches a Process command through the bus. RunCommandMessage does the same for console commands. Both return a context object with the exit code and output. PingWebhookMessage pings a URL, which is useful for monitoring scheduled tasks without spinning up a dedicated health-check service:

$this->bus->dispatch(new RunCommandMessage('cache:clear'));
$this->bus->dispatch(new PingWebhookMessage('GET', 'https://healthchecks.io/ping/abc123'));

The subprocess inheritance problem also got addressed with PhpSubprocess. When you run PHP with a custom memory limit (-d memory_limit=-1), child processes launched with Process don’t inherit it. PhpSubprocess does:

$sub = new PhpSubprocess(['bin/console', 'app:heavy-import']);

Security: three fixes for real situations

The profiler now shows how security badges were resolved during authentication: which ones passed, which failed, and why. Before, you had to add debug output manually when a custom authenticator wasn’t behaving.

Login throttling via RateLimiter now hashes PII in logs automatically. IP addresses and usernames get hashed with the kernel secret before they’re written. No config needed, no regex on log lines.

Firewall patterns now accept arrays:

firewalls:
    no_security:
        pattern:
            - "^/register$"
            - "^/api/webhooks/"

No more regex gymnastics for multi-path exclusions.

Logout without a dummy controller

The logout route used to require a controller that did nothing but throw an exception, with a comment explaining that yes, this is intentional. 6.4 eliminates that:

# config/routes/security.yaml
_security_logout:
    resource: security.route_loader.logout
    type: service

The route loader handles it. The dummy controller is gone. Flex updates the recipe.

The serializer in better shape

Three serializer improvements that each solve a real problem.

Class-level #[Groups] attribute: apply a group to the entire class, then override per property. Useful when a resource has a default serialization group and a few fields that need finer control.

Translatable objects now have a dedicated normalizer. Translatable strings (wrapping Doctrine’s TranslatableInterface) get translated to the locale passed via NORMALIZATION_LOCALE_KEY during normalization. Before this, you had to write a custom normalizer.

In debug mode, JSON decoding errors now use seld/jsonlint for better messages. Instead of “Syntax error”, you get the line and what actually went wrong:

Parse error on line 1: {'foo': 'bar'}
           ^ Invalid string, used single quotes instead of double quotes

Profilers for the things that weren’t HTTP requests

The command profiler extends the existing profiler to console commands. Add --profile to any command and get a full profiler entry: input/output, execution time, memory, database queries, log messages. Commands that used to need --verbose plus manual timing now have the same debugging experience as HTTP requests.

The workflow profiler does the same for state machines. A new panel shows a graphical representation of your workflows and which transitions fired during the request. Zero configuration.

The DX accumulation

Several smaller additions that compound.

renderBlock() and renderBlockView() on AbstractController let you render a named Twig block and return it as a Response or string. Handy for Turbo Stream responses where you want to update a fragment without a full controller action.

The defined env var processor returns a boolean rather than the value: true if the variable exists and is non-empty, false otherwise. Useful for feature flags driven by environment variables:

parameters:
    is_feature_enabled: '%env(defined:FEATURE_FLAG_KEY)%'

HttpClient now accepts max_retries per request, overriding the global retry strategy. The Finder component’s filter() method accepts a second argument to prune entire directories early, which matters when you’re searching large trees.

The BrowserKit click() method now accepts server parameters as extra headers, useful in functional tests that need to simulate authenticated API calls while following links.

Impersonation becomes usable in templates

Two new Twig helpers: impersonation_path() and impersonation_url(). They generate the correct URLs including the switch-user query parameter, which is configurable and has no business being hardcoded in templates. Pair them with the existing impersonation_exit_path() for the full admin impersonation flow.

Locale control, everywhere it was missing

Three gaps filled. TemplatedEmail now has a locale() method for rendering emails in the recipient’s language. The locale switcher’s runWithLocale() now passes the locale as an argument to the callback, so you don’t have to capture it from the outer scope. And app.enabledLocales is available in Twig, so you can build language switchers without hardcoding locale lists.

Deploying to read-only filesystems

APP_BUILD_DIR is now an environment variable recognized by the kernel. Set it to redirect compiled artifacts (router cache, Doctrine proxies, preloaded translations) to a directory that exists, even when the default cache directory doesn’t. The MicroKernelTrait uses it automatically. The WarmableInterface gained a $buildDir parameter to support this separation: custom cache warmers that write read-only artifacts should update accordingly.

Typed class constants

Class constants have been untyped since their introduction. PHP 8.3 fixes that:

interface HasVersion {
    const string VERSION;
}

class App implements HasVersion {
    const string VERSION = '1.0.0';
}

Without typed constants, an interface constant could be overridden with a completely different type in an implementing class and nothing would complain. Typed constants close that gap, and on interface-driven codebases the impact is immediate.

Dynamic class constant access

A gap that required a workaround since constants were introduced:

$name = 'STATUS';
echo MyClass::{$name}; // now works

Before, accessing a constant with a dynamic name meant calling constant('MyClass::STATUS'). The new syntax is consistent with how PHP already handles variable variables and dynamic method calls.

readonly can now be amended in clone

A specific but genuinely annoying limitation of 8.1 readonly: you couldn’t clone an object and change a readonly property. 8.3 adds the ability to reinitialize readonly properties during cloning, which makes immutable value objects usable in a lot more patterns.

json_validate()

if (json_validate($string)) {
    $data = json_decode($string);
}

Before 8.3, the only way to validate a JSON string was to decode it and check for errors. json_validate() checks without allocating the decoded structure, which matters when you only need to know if the string is valid JSON, not what’s in it.

Randomizer improvements

getBytesFromString() generates a random string composed only of characters from a given set:

$rng = new Random\Randomizer();
$token = $rng->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 32);

The previous approach: str_split, array_map, random selection, implode. It worked, but it was longer than it had any right to be.

8.3 is for the teams that adopt PHP versions quickly and want the incremental improvements. The typed constants alone are worth it on any codebase with interface constants.

#[\Override] makes inheritance explicit

Before 8.3, nothing stopped you from writing a method you thought was overriding a parent’s, when you had a typo in the name or the parent had quietly removed it. Silent bugs, zero feedback from the engine.

class Cache {
    #[\Override]
    public function get(string $key): mixed {
        // Engine verifies this method exists in a parent or interface
    }
}

If the method doesn’t exist in any parent class or implemented interface, PHP throws an error. Same concept as Java’s @Override or C#’s override, finally in PHP.

final on trait methods

Traits have always had rough edges in PHP’s OOP model. One specific problem: a class using a trait could override any of its methods, undermining whatever guarantees the trait was trying to provide. 8.3 lets the trait itself mark a method as final:

trait Singleton {
    final public static function getInstance(): static {
        // ...
    }
}

Now a class using the trait cannot override getInstance(). The guarantee holds.

Anonymous classes can be readonly

PHP 8.1 brought readonly classes. Anonymous classes were left out for some reason. 8.3 fixes that:

$point = new readonly class(3, 4) {
    public function __construct(
        public float $x,
        public float $y,
    ) {}
};

Handy when you need a throwaway immutable value object without the ceremony of naming it.

Static variable initializers accept expressions

A small but long-standing restriction: static variable initializers only accepted constant expressions, no function calls. 8.3 drops that constraint:

function connection(): PDO {
    static $pdo = new PDO(getenv('DATABASE_URL'));
    return $pdo;
}

The initializer runs once on first call, the static variable persists. Achievable with a null-check before, this is just cleaner.

mb_str_pad() finally exists

str_pad() has always been byte-aware, not character-aware. For multibyte strings (Arabic, Japanese, accented characters) it produced wrong output. 8.3 finally adds the multibyte variant:

$padded = mb_str_pad('日本', 10, '*', STR_PAD_BOTH);

The function respects character boundaries, not byte counts.

str_increment() and str_decrement()

PHP’s ++ operator on strings has a history of quirks: it increments letter sequences ('a' → 'b', 'z' → 'aa'), but -- never worked symmetrically. The behavior was surprising enough that 8.3 deprecates ++/-- on non-alphanumeric strings and introduces explicit functions:

echo str_increment('a');  // b
echo str_increment('Az'); // Ba
echo str_decrement('b');  // a
echo str_decrement('Ba'); // Az

The functions make the intent obvious and the behavior predictable.

Random\Randomizer gets float support

8.3 fills in the float side of the Randomizer API:

$rng = new Random\Randomizer();

// A float in [0.0, 1.0)
$f = $rng->nextFloat();

// A float in a specific range with controlled boundary inclusion
$f = $rng->getFloat(1.5, 3.5, Random\IntervalBoundary::ClosedOpen);

IntervalBoundary is a new enum with four values: ClosedOpen, ClosedClosed, OpenClosed, OpenOpen. This matters for statistical correctness: the naive approach of rand() / getrandmax() doesn’t produce a uniform distribution over floats.

The Date exception hierarchy

Date/time errors in PHP used to throw generic exceptions with no way to tell “malformed string” from “invalid timezone” without parsing the message yourself. 8.3 adds a proper hierarchy:

try {
    new DateTimeImmutable('not a date');
} catch (DateMalformedStringException $e) {
    // specifically a parsing failure
} catch (DateException $e) {
    // other date-related errors
}

The full tree: DateError (engine-level), DateException (base), with specific subclasses for invalid timezone, malformed interval string, malformed period string, and malformed date string.

gc_status() tells you more

gc_status() now returns eight additional fields: running, protected, full, buffer_size, and timing breakdowns (application_time, collector_time, destructor_time, free_time). If you’re profiling memory pressure or GC pauses, this data was previously unavailable without pulling in an extension.

strrchr() grows a direction argument

strrchr() (find the last occurrence of a character, return from there to end) now accepts a $before_needle boolean, matching the API of strstr():

$path = '/var/www/html/index.php';
echo strrchr($path, '/', before_needle: true);  // /var/www/html
echo strrchr($path, '/');                        // /index.php

A function that’s been in PHP since 1994, finally consistent with its sibling.

Deprecations worth noting

get_class() and get_parent_class() without arguments now emit deprecation notices. The argumentless forms relied on implicit $this context, which was easy to misread. Pass the object explicitly.

assert_options() and the ASSERT_* constants are deprecated in favor of the zend.assertions INI directive, which is the right tool for controlling assertion behavior across environments.

The ++/-- operators on empty strings and non-numeric non-alphanumeric strings now emit deprecation warnings. The behavior was undefined territory. 8.3 starts the migration toward defined behavior in 9.0.

Stack overflow protection

Two new INI directives: zend.max_allowed_stack_size sets a hard limit on PHP’s stack depth, and zend.reserved_stack_size sets aside a buffer for cleanup after a limit is hit. Before 8.3, deeply recursive code could just crash at the OS level. Now PHP catches it and throws an Error with a useful message.

Errors as resources

Before 3.2, error handling was outside the resource model. Exceptions were caught by a Symfony event listener and converted to a response, with limited control over the shape of the output.

3.2 makes errors first-class ApiResource classes compliant with RFC 9457 (Problem Details for HTTP APIs). The built-in error class is ApiPlatform\ApiResource\Error, and you can create your own:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

When this exception is thrown anywhere in the state layer, API Platform catches it, serializes it as a Problem Detail response, and generates a proper OpenAPI schema for it. The error type, title, detail, and status are all part of the resource contract — not hardcoded strings in a listener.

Sub-resources without the workarounds

Sub-resources existed in 2.x but were removed in 3.0 because they were tightly coupled to the old data provider model and couldn’t be cleanly mapped to the new operation-first architecture. 3.2 reintroduces them in a way that fits.

A sub-resource is a resource accessible through a parent resource’s URI. In 3.2, it is declared directly on the child resource using uriTemplate:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

The Link descriptor makes the relationship explicit. The provider receives bookId in $uriVariables and can use it to scope the query. No magic inference, no implicit joins — the URI structure and the data access are both declared.

canonical_uri_template for multiple access paths

When a resource is accessible through multiple URIs (a direct endpoint and a sub-resource endpoint), OpenAPI needs to know which URI is canonical for $ref links. 3.2 uses the top-level uriTemplate on ApiResource as the default canonical URI. For finer control, the canonical_uri_template option can be passed via extraProperties on any operation to override it explicitly.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

The generated OpenAPI spec uses the canonical URI for schema references, keeping the document consistent when a resource appears under several paths.

Union and intersection types

3.2 adds support for PHP union and intersection types in the metadata layer. A property declared as Book|Magazine generates a proper oneOf schema in OpenAPI. This was previously unsupported — you had to fall back to an untyped mixed or annotate the property manually.

Event listeners made optional

The last compatibility shim from 2.x was the ability to use Symfony event listeners on the kernel.request and kernel.view events to intercept API Platform’s data flow. 3.2 does not remove them, but introduces an opt-out: setting event_listeners_backward_compatibility_layer: false in the API Platform configuration disables the event-based hooks entirely. The replacement is a provider or processor decorated with another provider or processor. The event-based hook was stateful, order-dependent, and bypassed the operation context entirely. Decorated providers get the operation object and can call the inner provider when ready.

The state model is now complete

3.0 introduced the architecture. 3.1 added resource/entity separation. 3.2 closes the remaining gaps: errors have a resource contract, sub-resources have a clean declaration model, and the state layer now covers every extension point that event listeners once handled. The 2.x shims still exist, but opting out of them is now a single config flag.

The resource/entity split

In 2.x, API Platform worked best when your API resource and your persistence model were the same class. Using a DTO as the API surface was possible through the Input/Output DTO system, but that system was removed in 3.0 — it complicated the state model without enough benefit.

3.1 replaces it with something cleaner. The stateOptions parameter on an operation accepts a DoctrineOrmOptions object that points to a different entity:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

The provider receives the BookEntity objects from Doctrine and the serialization layer maps them to BookDto. The Doctrine filters, pagination, and ordering all work on BookEntity. The API surface exposes BookDto. The two can evolve independently.

This matters more than it looks. Your persistence model accumulates internal fields, relations, and columns that have no business being in your API. Before 3.1, you either exposed them anyway or built an elaborate normalizer to hide them. Now you declare what the API looks like as a separate class and let the framework handle the mapping.

PUT that follows the spec

Since version 1.0, API Platform’s PUT handler updated existing resources. Creating a resource via PUT — which the HTTP spec explicitly allows — was not supported. 3.1 adds uriTemplate-based creation:

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

With allowCreate: true, a PUT to a URI that does not exist creates the resource instead of returning 404. The identifier comes from the URI, not from the request body. This is what RFC 9110 describes for PUT: “If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response.”

It is a small flag, but it opens API Platform to use cases — idempotent resource creation, client-assigned identifiers — that previously required a custom controller.

Denormalization errors collected, not thrown

Before 3.1, deserialization errors stopped at the first problem. Send a request body with five invalid fields and get an error about the first one. Fix it, send again, find the second. Repeat five times.

3.1 adds a collect_denormalization_errors option on the operation that changes this behavior:

#[Post(collectDenormalizationErrors: true)]

With this enabled, API Platform catches all type errors and constraint violations during deserialization and returns them as a structured list in the response, formatted the same way as validation errors. One round-trip, full picture.

ApiResource::openapi replaces openapiContext

The old openapiContext parameter accepted a raw array that was merged into the generated OpenAPI schema — convenient but untyped. 3.1 introduces a first-class openapi parameter that accepts an OpenApiOperation object:

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Create a book',
            required: true,
        ),
        summary: 'Create a new book entry',
    )
)]

The old openapiContext array still works but is deprecated. The new approach is typed, IDE-friendly, and validates at construction time rather than at schema generation time. PHP 8.1 backed enums also get proper OpenAPI schema generation in 3.1 — a field typed as a backed enum produces a schema with enum values and the correct type, without any annotation.

The pattern is clear

3.0 established the architecture. 3.1 shows what that architecture enables: clean resource/entity separation without a parallel DTO system, RFC-correct HTTP semantics, better error reporting. None of these would have been as clean to implement on the 2.x data provider model. The features in 3.1 are the first proof that the rewrite was the right call.

Dynamic properties deprecated

PHP has always allowed adding properties to objects that weren’t declared in the class:

class User {}
$user = new User();
$user->name = 'Alice'; // no declaration, no error... until now

In 8.2, this triggers a deprecation notice. In PHP 9.0 it becomes a fatal error. The grace period exists, but the migration clock is running.

The reasoning is solid: dynamic properties are a classic source of typos that silently pass (write $user->nmae and PHP just creates a new property instead of complaining). Explicit declarations make the class contract clear and make tooling actually useful.

Migration is mostly mechanical: declare the properties, or slap #[AllowDynamicProperties] on legacy classes you can’t touch yet.

Readonly classes

8.1 added readonly for individual properties. 8.2 adds it to the class declaration itself:

readonly class Point {
    public function __construct(
        public float $x,
        public float $y,
        public float $z,
    ) {}
}

All promoted and explicitly declared properties become readonly automatically. Value objects (coordinates, money amounts, identifiers) are the obvious target. The syntax is clean and the intent reads clearly.

One constraint: readonly classes can’t have non-typed properties, which were already a bad idea with readonly anyway.

DNF types

Disjunctive Normal Form types let you combine union and intersection types:

function process(Countable&Iterator|null $collection): void { ... }

(Countable&Iterator)|null: an object that implements both interfaces, or null. This covers type expressions that 8.0 union types and 8.1 intersection types each got partway to but couldn’t represent together.

The Random extension

A dedicated Random extension replaces the scattered rand(), mt_rand(), random_int() functions with an object-oriented API:

$rng = new Random\Randomizer();
$rng->getInt(1, 100);
$rng->shuffleArray($items);

Engines are swappable: Mersenne Twister, PCG64, Xoshiro256StarStar, or CryptoSafeEngine for security-sensitive contexts. Same code, seeded deterministic engine in tests, cryptographic engine in production.

8.2 is a consolidation release. The dynamic properties deprecation is the one decision you need to make now.

null, false, and true as standalone types

PHP has had nullable types since 7.1 and union types since 8.0, but null as a standalone type declaration wasn’t valid. 8.2 fixes that:

function alwaysNull(): null {
    return null;
}

function disabled(): false {
    return false;
}

function enabled(): true {
    return true;
}

false and true as standalone types are useful when you need to be precise about what a function can actually return. It’s narrow but correct: a function that returns false on failure and a string on success should declare string|false, and now both sides of that union are real types.

Constants in traits

Traits could hold properties and methods. Constants were the odd gap. 8.2 closes it:

trait Timestamps {
    public const DATE_FORMAT = 'Y-m-d H:i:s';

    public function formatCreatedAt(): string {
        return $this->createdAt->format(self::DATE_FORMAT);
    }
}

class Article {
    use Timestamps;
}

echo Article::DATE_FORMAT; // 'Y-m-d H:i:s'

The constant belongs to the class that uses the trait, not the trait itself, so you can’t access Timestamps::DATE_FORMAT directly. Expected scoping behavior, consistent with how trait methods already work.

#[SensitiveParameter]

Stack traces have always been a liability: function arguments get logged verbatim, which means passwords and tokens end up in your error logs and monitoring dashboards. 8.2 adds an attribute to stop that:

function authenticate(
    string $user,
    #[\SensitiveParameter] string $password,
): bool {
    // if this throws, the stack trace shows:
    // authenticate('alice', Object(SensitiveParameterValue))
    return hash('sha256', $password) === getStoredHash($user);
}

The parameter value in the trace gets replaced with a SensitiveParameterValue object. One attribute, zero excuses not to add it to every function that touches credentials.

Deprecated string interpolation syntaxes

Two ways to interpolate expressions inside strings are deprecated in 8.2:

$name = 'world';

// These are deprecated:
echo "Hello ${name}";       // use "$name" or "{$name}"
echo "Hello ${getName()}";  // use "{$this->getName()}"

The ${...} forms created ambiguity between variable variables and expressions. The cleaner {$...} syntax has always been there and does the same thing. This is mostly a search-and-replace job in codebases that picked up the deprecated forms out of habit.

utf8_encode() and utf8_decode() deprecated

These two functions are deprecated in 8.2 and gone in 9.0. Their behavior was always narrower than the names suggested: utf8_encode() converts ISO-8859-1 to UTF-8, not “any encoding to UTF-8.”

// Deprecated in 8.2:
$utf8 = utf8_encode($latin1String);

// Use instead:
$utf8 = mb_convert_encoding($latin1String, 'UTF-8', 'ISO-8859-1');

mb_convert_encoding() or iconv() handle the general case. If you’re actually dealing with Latin-1 input, the replacement is a direct swap.

Locale-independent string functions

Several string functions silently varied behavior based on the system locale, producing different results in production versus a dev container. In 8.2, they’re locale-independent and ASCII-only:

// strtolower, strtoupper, stristr, stripos, strripos,
// lcfirst, ucfirst, ucwords, str_ireplace now do ASCII case conversion only.
// For locale-aware behavior, use mb_* equivalents:
$lowered = mb_strtolower($text, 'UTF-8');

This is a correctness fix. If your code was relying on locale-sensitive behavior from these functions, it was already broken on systems with different locale configurations. 8.2 makes the behavior deterministic everywhere, which is what you actually wanted.

str_split() on empty string

A quiet behavior change worth noting:

// PHP 8.1: str_split('') === ['']
// PHP 8.2: str_split('') === []

The new behavior makes more sense: splitting nothing produces nothing. If you’re checking count(str_split($input)), an empty input no longer produces a count of 1.

The old model had a conceptual leak. DataProviderInterface and DataPersisterInterface were called for every HTTP request, but the provider received the operation context as a hint — not as a contract. A collection provider and an item provider were separate interfaces, but both lived in the same mental bucket: “things that return data.” The HTTP layer knew what was being requested; the provider had to reconstruct that knowledge from context clues passed in the $context array.

3.0 inverts the model. Operations are declared first. Data access is wired to operations.

State providers replaced data providers

The old DataProviderInterface is gone. The replacement is ProviderInterface:

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}