"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.

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.

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.

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.

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.

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.

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']);
    }
}

The difference is not syntactic. In 2.x, you registered a provider and API Platform called it for any matching resource. In 3.0, you bind a provider to a specific operation. The provider no longer guesses what triggered it — the operation object it receives is the contract.

State processors replaced data persisters

DataPersisterInterface had the same problem on the write side: one class handling create, update, and delete, distinguishing them by inspecting the HTTP method or the object state. ProcessorInterface receives the operation as a typed argument:

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

More usefully: you can bind a different processor per operation. The delete operation gets one that removes. The post operation gets one that validates and stores. No switch statement, no method inspection, no shared class trying to be three things at once.

Operations declared explicitly in PHP 8.1 attributes

The other half of 3.0 is the metadata layer. Doctrine annotations are replaced by PHP 8.1 native attributes, and each operation is declared explicitly on the resource class:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

This is more verbose than @ApiResource with magic defaults. It is also explicit. You know exactly what HTTP operations exist for this resource, what retrieves data, what writes it, and where the logic lives. The defaults of 2.x were convenient until the day you needed to override one and couldn’t figure out which service to decorate without reading the source.

PHP 8.1 was not a coincidence

The hard requirement for PHP 8.1 is load-bearing. First-class callables make filter registration cleaner. The immutability of operation metadata is enforced through cloning patterns (withX() methods) that rely on named arguments and promoted constructor properties — PHP 8.0 foundations the architecture builds on heavily.

More practically: the full expression of 3.0’s architecture — typed operations, operation-scoped providers, explicit metadata — needed 8.1 to not feel like workarounds. Dropping PHP 7.x and 8.0 was not a housekeeping decision.

The migration is real work

The jump from 2.x to 3.0 is not a version bump. Every DataProvider becomes a ProviderInterface. Every DataPersister becomes a ProcessorInterface. Annotations become attributes. Custom normalizers and filters may need restructuring. The upgrade guide documents all of it, but “documented” does not mean “fast.”

What you get on the other side is an architecture that scales without the ambient complexity of 2.x: no more guessing which interface to implement, no more $this->supports() chains, no more invisible defaults quietly overriding explicit config.

3.0 is the API Platform you’d design from scratch knowing what you know after years of 2.x. The price is the migration. The version number is honest about that.

It ships with the framework. It has retry logic, native AMQP support, first-party documentation. Our setup looked artisanal by comparison.

Fair question. We took it seriously. Here’s what we found.

Wiring the topology by hand

Swarrot is a consumer library that wraps the PECL AMQP extension. It reads bytes from a queue, runs them through a chain of processors (their term for middleware), and lets your code decide what to do with the payload. That’s really it.

The middleware chain is the interesting part. Processors are nested decorators, each wrapping the next. The outer layers handle infrastructure concerns before the message even reaches your business logic:

middleware_stack:
    - configurator: 'swarrot.processor.signal_handler'
    - configurator: 'swarrot.processor.max_execution_time'
    - configurator: 'swarrot.processor.exception_catcher'
    - configurator: 'swarrot.processor.doctrine_object_manager'
    - configurator: 'swarrot.processor.ack'
    - configurator: 'app.processor.retry'

signal_handler sits at the top because it needs to catch SIGTERM before any other processor sees it. ack sits near the bottom because you only acknowledge the message after processing succeeds. The order is not arbitrary, and it’s entirely visible in configuration.

The topology is equally explicit. You declare everything yourself: exchanges, routing keys, retry queues, dead-letter queues:

messages_types:
    content.ingest:
        exchange: e.app.content
        routing_key: q.app.content.ingest
    content.ingest_retry:
        exchange: e.app.content
        routing_key: q.app.content.ingest.retry
    content.ingest_dead:
        exchange: e.app.content
        routing_key: q.app.content.ingest.dead

Three entries per logical message type: main queue, retry queue, dead-letter queue. Everything that exists on the broker is named right here. The config is verbose but honest: no inference, no convention over configuration. If a queue exists in RabbitMQ, you can trace it to a single line of YAML.

When the class name becomes the route

Symfony Messenger operates one level higher. You define a message class, a handler, and a transport. The library handles serialization, routing, retry, and failure queues automatically.

class IngestContent
{
    public function __construct(
        public readonly string $contentId,
        public readonly string $source,
    ) {}
}

framework:
    messenger:
        transports:
            async:
                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
                retry_strategy:
                    max_retries: 3
                    delay: 1000
        routing:
            'App\Message\IngestContent': async

Messenger serializes the object, puts it on the transport, and deserializes it on the other end into the correct class. No manual topology, no explicit exchange names. The class name is the routing primitive.

That last sentence is exactly where things got complicated for us.

Where typing becomes coupling

Messenger assumes that the producer and the consumer share a PHP class definition. That’s fine for a single app, or for services that share a dedicated contracts package. In a monorepo of independent Symfony applications, it creates coupling that simply doesn’t exist today.

Take a content ingestion message that twelve services consume. With Swarrot, each service reads the raw JSON payload and picks the fields it cares about. Adding a new field means updating the producer. Consumers that don’t need the field keep working without any modification.

With Messenger, IngestContent must be defined somewhere that all twelve services can reference. That means either:

• A shared PHP package, versioned, deployed, and maintained across services. Every schema change becomes a cross-service coordination exercise.
• Duplicated classes in each service, which drift silently apart under pressure.

Neither is free. The shared package approach inverts the ownership model: the message schema becomes a dependency rather than a contract defined at the boundary. The duplication approach is just the original problem deferred.

The root difference is what a message represents. Messenger is designed for typed commands: an object that carries meaning and dispatches to a specific handler. Swarrot treats messages as opaque data: bytes that flow through a topology, processed by whatever consumer happens to be listening. If your messages are data, the extra abstraction Messenger adds doesn’t help you. It creates friction.

The blocker

The serialization problem was the decisive one. In a monorepo where services are autonomous, sharing PHP classes between them isn’t architecturally neutral: it’s a coupling decision that makes future changes harder. We would have been trading a nominally “legacy” library for a more modern one while introducing exactly the kind of tight coupling we’d spent years avoiding.

There were secondary concerns too. The PECL AMQP extension gives direct access to broker features (message priorities, per-queue TTL, headers exchange routing) that Messenger abstracts away. And migrating fifteen consumers without a flag day means running both libraries in parallel, which is a real operational constraint.

But the serialization issue alone would have been enough.

Data or commands: that’s the question

The choice isn’t about library quality. Messenger is well-maintained, well-documented, and integrates cleanly into the Symfony ecosystem.

The question to ask first is: what are your messages?

If they are typed commands with a known schema and a single authoritative consumer, Messenger is a natural fit. You write a class, a handler, configure a transport, and the infrastructure handles the rest.

If they are data payloads consumed by multiple independent services, each of which owns its own deserialization, the abstraction Messenger adds works against you. Swarrot’s explicit topology and raw payload model give you more control where you actually need it.

One real limitation to keep in mind: Swarrot is tied to the PECL AMQP extension, which only implements AMQP 0-9-1. That means RabbitMQ (or a compatible broker) is a hard dependency. If your infrastructure ever moves toward an AMQP 1.0 broker (Azure Service Bus, ActiveMQ Artemis), Swarrot can’t follow. Messenger’s transport layer abstracts this cleanly: changing brokers means changing a DSN, not rewriting consumers.

If broker portability is a requirement, or likely to become one, that changes the calculus significantly.

Swarrot isn’t legacy to migrate away from. For now, it’s the right fit: AMQP routing as the primitive, messages as data, RabbitMQ as a long-term infrastructure choice.

That could change. A shared contracts package, a new broker requirement, a greenfield service that doesn’t carry the existing topology weight: any of these could tip the balance toward Messenger. The library isn’t wrong for this platform. It may just be the right answer for a future version of it.

This isn’t just a version bump. It’s a commitment to build against the current language instead of the historical floor.

The security system, finally rebuilt

The Symfony security component has two systems. The old one (AnonymousToken, GuardAuthenticatorInterface, a tangle of interfaces that made you implement methods you didn’t need) had been deprecated. 6.0 removes it entirely.

The new security system (security.enable_authenticator_manager: true in 5.x) is now the only system. It’s cleaner: one interface to implement, clear separation between authentication and authorization, passport-based credential checking. The upgrade from the old guard authenticators isn’t painless, but the destination is a lot less confusing.

The Filesystem Path class

Working with filesystem paths in PHP is basically a string manipulation problem. __DIR__, concatenation, realpath(), platform-specific separators: the standard library gives you primitives but no real model.

The new Path class handles this:

use Symfony\Component\Filesystem\Path;

Path::join('/var/www', 'html', '../uploads'); // /var/www/uploads
Path::makeRelative('/var/www/html', '/var/www'); // html
Path::isAbsolute('./relative/path'); // false

Cross-platform, no side effects, no filesystem access needed. Also in 6.0: nested .gitignore pattern support in Finder.

Enums in the form system

Building on 5.4’s groundwork, 6.0 takes enum support further. BackedEnum values round-trip through forms and the serializer without custom transformers. The form component understands enum cases as choice options out of the box.

What 6.0 removes

The removal list is extensive: the old security system, the Templating component, PHP annotations support (replaced by native attributes), Doctrine Cache support, ContainerAwareTrait. Six years of accumulated @deprecated markers, finally cleaned out.

Apps that took 5.4 deprecation warnings seriously had a clean upgrade path. Apps that didn’t had work to do.

Tab completion was always the gap

The Console component got shell autocompletion, and it’s properly integrated: define a complete() method on your command, and Tab in Bash will suggest valid values for options and arguments.

class DeployCommand extends Command
{
    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
    {
        if ($input->mustSuggestOptionValuesFor('env')) {
            $suggestions->suggestValues(['prod', 'staging', 'dev']);
        }
    }
}

All built-in Symfony commands got completion too: debug:router, cache:pool:clear, lint:yaml, and about fifteen others. Run bin/console completion bash >> ~/.bashrc and you’re done.

Messenger, now with attributes and batch processing

The #[AsMessageHandler] attribute replaces the old MessageHandlerInterface. Less boilerplate, and you can now configure transport affinity and priority directly on the attribute:

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class SendWelcomeEmailHandler
{
    public function __invoke(UserRegistered $message): void { ... }
}

The other significant addition: BatchHandlerInterface. When you’re inserting a thousand rows, handling messages one by one is wasteful. Batch handlers collect messages and process them in groups. The default batch size is 10, controlled by BatchHandlerTrait::shouldFlush(). The Acknowledger handles individual success and failure within the batch.

reset_on_message: true in the Messenger config resets container services between messages. Previously, a Monolog buffer could fill up across message handling and nobody noticed until production. This prevents that class of statefulness bug without requiring manual cleanup.

The DI container gets more expressive

Three changes that matter in practice.

Union and intersection types now autowire. PHP 8.1 added intersection types, and Symfony 6.0 wires them:

public function __construct(
    private NormalizerInterface&DenormalizerInterface $serializer
) {}

This works as long as both interfaces point to the same service through autowiring aliases.

TaggedIterator and TaggedLocator attributes gained defaultPriorityMethod and defaultIndexMethod options. You no longer need YAML to express ordering or indexing for tagged services:

public function __construct(
    #[TaggedIterator(tag: 'app.handler', defaultPriorityMethod: 'getPriority')]
    private iterable $handlers,
) {}

SubscribedService (the attribute that replaces the implicit magic of ServiceSubscriberTrait) makes lazy service access explicit and typeable:

#[SubscribedService]
private function mailer(): MailerInterface
{
    return $this->container->get(__METHOD__);
}

Validation gets three new tools

CssColor validates CSS color values in whatever formats you care about: hex, RGB, HSL, named colors, or any mix. Useful for theme config fields where you want to accept #ff0000 but not red, or vice versa.

#[Assert\CssColor(formats: Assert\CssColor::HEX_LONG)]
private string $brandColor;

Cidr validates CIDR notation for IPv4 and IPv6, with options to pin the version and constrain the netmask range. Infrastructure tools and network config forms finally have a first-class constraint.

The third addition isn’t a new constraint. It’s PHP 8.1 nested attributes making existing compound constraints usable without XML. AtLeastOneOf, Collection, All, Sequentially: all of these previously required annotation workarounds. Now they just work as attributes:

#[Assert\Collection(
    fields: [
        'email' => new Assert\Email(),
        'role'  => [new Assert\NotBlank(), new Assert\Choice(['admin', 'user'])],
    ]
)]
private array $payload;

Serializer, cleaned up

Two things. First, serialization context is now configurable globally instead of being repeated on every serialize() call:

# config/packages/serializer.yaml
serializer:
    default_context:
        enable_max_depth: true

Second, the COLLECT_DENORMALIZATION_ERRORS option changes how the serializer handles type errors on deserialization. Instead of throwing on the first problem, it collects all of them and surfaces them through PartialDenormalizationException. If you’re writing an API that deserializes request bodies, this is the difference between returning “first field that fails” and “all fields that fail” in a single response.

The string utilities nobody knew they needed

trimPrefix() and trimSuffix() on the UnicodeString / ByteString classes. Not glamorous, but stripping a known prefix with ltrim() is a subtle footgun: it strips characters, not strings. These are correct:

use function Symfony\Component\String\u;

u('file-image-001.png')->trimPrefix('file-');   // 'image-001.png'
u('report.html.twig')->trimSuffix('.twig');     // 'report.html'

Also in this release: NilUlid for zero-value ULIDs, perMonth() and perYear() on RateLimiter for when hourly limits don’t make sense, and appendToFile() in the Filesystem component gained an optional LOCK_EX parameter for concurrent writers.

Debugging the environment

debug:dotenv is a new console command that shows which .env files were loaded and where each value came from. When you have .env, .env.local, .env.test, and .env.test.local all fighting each other and something is wrong, this command tells you exactly which file won. It only shows up when the Dotenv component is in use, which is the case for any standard Symfony app.

5.4 is the LTS, and its job is to carry as much of 6.0’s feature set as possible while keeping 5.x compatibility intact. It’s also the first Symfony release that actually understands PHP 8.1 features.

Enum support

PHP 8.1 introduced native enums. Symfony 5.4 embraces them immediately:

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

The EnumType form type renders enums as select fields, no custom transformers needed. The validator understands backed enums. The serializer maps enum values to their backing type and back. Three components updated in one shot, which meant migrating codebases from pseudo-enum constants to real PHP 8.1 enums was actually pretty smooth.

Security voter cache

The CacheableVoterInterface lets voters that always abstain on a given attribute signal that to the security system, which can then skip them on subsequent checks. For apps with many voters, the gain on permission checks adds up fast. Small change, noticeable in practice.

Messenger matures further

Messenger batch processing (handling multiple messages in a single transaction instead of one by one) is now stable. Rate limiting per transport. Dead letter queues get better tooling. After years as “experimental”, Messenger in 5.4 is finally the async foundation you can bet on for serious workloads.

Console grew a tab key

Symfony 5.4 ships shell autocompletion for all commands. Press Tab and the shell suggests command names, argument values, and option values. For built-in commands this works out of the box. For custom commands, add a complete() method:

use Symfony\Component\Console\Completion\CompletionInput;
use Symfony\Component\Console\Completion\CompletionSuggestions;

public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
{
    if ($input->mustSuggestOptionValuesFor('format')) {
        $suggestions->suggestValues(['json', 'xml', 'csv']);
    }
}

No interface required, just the method and Symfony picks it up. The community also went through all built-in commands (debug:router, cache:pool:clear, secrets:remove, lint:twig, and a dozen more) to add completions before the release.

Routes can be aliases now

The routing component now supports aliasing: one route can point to another. The obvious use case is renaming a route without breaking anything that still generates URLs with the old name.

# config/routes.yaml
admin_dashboard:
    path: /admin

# legacy name kept during transition
dashboard:
    alias: admin_dashboard
    deprecated:
        package: 'acme/my-bundle'
        version: '2.3'

Generating a URL with dashboard still works, but fires a deprecation notice. Clean rename paths for bundles that need to maintain public route names while moving on.

Exceptions map to HTTP status codes in config

Before 5.4, mapping an exception class to an HTTP status code meant implementing HttpExceptionInterface or writing a listener. Now it’s just a YAML entry:

# config/packages/framework.yaml
framework:
    exceptions:
        App\Exception\PaymentRequiredException:
            status_code: 402
            log_level: warning
        App\Exception\MaintenanceException:
            status_code: 503
            log_level: info

The exception doesn’t need to implement anything. The framework reads the map, sets the status code, logs at the configured level. Handy for domain exceptions that have no business knowing about HTTP.

Two new validator constraints

5.4 adds Cidr and CssColor to the Validator component.

Cidr validates network notation — IP address plus subnet mask — with control over which IP version to accept and bounds on the mask value:

#[Assert\Cidr(version: 4, netmaskMin: 16, netmaskMax: 28)]
private string $allowedSubnet;

CssColor validates that a string is a valid CSS color. Useful for theme editors, CMS config, or any UI that lets users pick colors:

#[Assert\CssColor(
    formats: Assert\CssColor::HEX_LONG,
    message: 'The accent color must be a 6-digit hex value.',
)]
private string $accentColor;

Nested PHP attributes for validation constraints

Symfony 5.2 added validator constraints as PHP attributes, but PHP 8.0 had a hard limit on nested attributes. Complex constraints like All, Collection, or AtLeastOneOf were impossible to express in attribute syntax alone. PHP 8.1 lifted that restriction, and 5.4 makes the most of it:

use Symfony\Component\Validator\Constraints as Assert;

class CartItem
{
    #[Assert\All([
        new Assert\NotNull(),
        new Assert\Range(min: 1),
    ])]
    private array $quantities;

    #[Assert\AtLeastOneOf(
        constraints: [new Assert\Email(), new Assert\Url()],
        message: 'Must be a valid email or URL.',
    )]
    private string $contact;
}

No annotation doc-blocks, no XML mapping. Pure PHP 8.1 attributes all the way down.

Dependency injection: three things worth knowing

Tagged iterators can now be injected into service locators, which previously only accepted explicit service lists. Union type autowiring works when both sides of the union resolve to the same service, which is common with serializer interfaces:

public function __construct(
    private NormalizerInterface & DenormalizerInterface $serializer
) {}

#[SubscribedService] replaces the automatic introspection that ServiceSubscriberTrait did implicitly. It’s now an explicit attribute on methods, which makes the dependency visible without any magic:

use Symfony\Contracts\Service\Attribute\SubscribedService;

class SomeService implements ServiceSubscriberInterface
{
    #[SubscribedService]
    private function router(): RouterInterface
    {
        return $this->container->get(__METHOD__);
    }
}

Messenger: attributes, worker state, and service reset

Messenger handlers can drop the MessageHandlerInterface in favor of #[AsMessageHandler], which also lets you bind a handler to a specific transport and set its priority, all without touching YAML:

#[AsMessageHandler(fromTransport: 'async', priority: 10)]
class ProcessOrderHandler
{
    public function __invoke(ProcessOrder $message): void { /* ... */ }
}

Worker state is now inspectable via WorkerMetadata inside event listeners, useful when you have workers on multiple transports and need to know which one fired a given event.

Long-running workers accumulate state across messages: entity manager buffers, in-memory caches, open connections. The new reset_on_message option takes care of resetting all resettable services between messages:

framework:
    messenger:
        reset_on_message: true

Serializer: collect errors instead of throwing

Deserializing external JSON into a typed DTO used to throw on the very first type mismatch. The COLLECT_DENORMALIZATION_ERRORS option changes that: all type errors get collected into a PartialDenormalizationException, so you can return a proper 400 with a full list of field-level problems:

try {
    $dto = $serializer->deserialize($request->getContent(), OrderDto::class, 'json', [
        DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true,
    ]);
} catch (PartialDenormalizationException $e) {
    return $this->json(
        array_map(fn($err) => ['path' => $err->getPath(), 'expected' => $err->getExpectedTypes()], $e->getErrors()),
        400
    );
}

The serializer’s default context can also be set globally in YAML, so you stop passing the same options on every call.

Language negotiation out of the box

Two new framework options handle the Accept-Language header without custom listeners:

framework:
    enabled_locales: ['en', 'fr', 'de']
    set_locale_from_accept_language: true
    set_content_language_from_locale: true

With this in place, Symfony reads the browser’s preferred language, picks the best match from enabled_locales, sets the request locale, and adds a Content-Language header to the response. The {_locale} route attribute still takes precedence when present.

Translation: extraction, not update

The translation:update command is renamed to translation:extract. The old name sticks around as deprecated. The distinction matters: the command never writes to a database, it extracts translatable strings from source files. The new name finally says what it does.

lint:xliff also gains a --format=github option that outputs errors as GitHub Actions annotations, so translation lint failures show up as PR review comments instead of getting buried in log output.

Controller shortcuts pruned

Three AbstractController shortcuts are deprecated: getDoctrine(), dispatchMessage(), and the generic get() method for pulling arbitrary services from the container. The direction is explicit constructor injection. For getDoctrine() specifically:

// before
$em = $this->getDoctrine()->getManager();

// after — inject it directly
public function __construct(private EntityManagerInterface $em) {}

Request::get() is also deprecated. It searched route attributes, query string, and POST body in an undocumented order, which was a great way to get surprising results. Use $request->query->get(), $request->request->get(), or $request->attributes->get() and be explicit about where the value comes from.

The Path utility class

The Filesystem component gets a Path class ported from webmozart/path-util. It handles the awkward cases that dirname() and realpath() fumble:

use Symfony\Component\Filesystem\Path;

Path::canonicalize('../config/../config/services.yaml'); // '../config/services.yaml'
Path::getDirectory('C:/');                               // 'C:/' (dirname() returns '.')
Path::getLongestCommonBasePath([
    '/var/www/project/src/Controller/FooController.php',
    '/var/www/project/src/Controller/BarController.php',
    '/var/www/project/src/Entity/User.php',
]);
// '/var/www/project/src'

Useful whenever your code deals with paths that cross OS boundaries or involve relative segments.

Smaller things that add up

debug:dotenv shows which .env files were loaded and what value each variable resolves to. The first thing you reach for when environment-specific behavior is acting up.

The String component adds trimPrefix() and trimSuffix() for removing known prefixes or suffixes without writing a substr calculation:

u('file-image-0001.png')->trimPrefix('file-');    // 'image-0001.png'
u('template.html.twig')->trimSuffix('.twig');      // 'template.html'

DomCrawler gets innerText(), which returns only the direct text of a node, excluding child elements. text() returns everything including nested text; innerText() returns just the node’s own content. Small difference, but it matters when scraping.

The RateLimiter component extends its interval support to perMonth() and perYear(), for apps that need to limit events over longer windows: newsletter sends, API quota resets, annual plan limits.

The Finder component now respects .gitignore files in all subdirectories when you call ignoreVCSIgnored(true), not just the root. Child directory rules override parent rules, exactly like git itself.

The LTS window

5.4 gets bug fixes until November 2024 and security fixes until November 2025. The migration from 5.4 to 6.4 (the next LTS) is intentionally smooth: fix the 5.4 deprecation warnings, and the 6.x jump is mechanical.

The deprecation layer in 5.4 points at everything 6.0 removes: the remaining pieces of the old security system, ContainerAwareTrait, and a handful of legacy form and serializer patterns.

Deleting them naively wasn’t an option. “Keep the last 50” loses all historical context for articles that haven’t been touched in a year. “Keep one per day” loses all the detail for content that’s actively being edited. What we needed was a distribution that matched how revisions are actually used: dense coverage for recent history, sparse coverage for old history.

That’s a logarithmic distribution. And building it required raw SQL.

Why simple strategies fail

The appeal of a fixed window is obvious: keep the N most recent revisions and delete the rest. It’s one line of SQL and zero math. The problem is that it treats a revision from yesterday and a revision from three years ago as equally valuable, which they aren’t. An editor who opens an article from 2017 doesn’t need its last 50 versions; they might need one per quarter. An article that shipped this morning might need every save from the past hour.

A time-based strategy (one revision per calendar day) has the opposite problem: it’s too aggressive for active content. If an article gets 30 saves between 09:00 and 10:00, all of them except one disappear. That’s not history, that’s erasure.

Neither strategy can express “keep more detail for recent content, less for old content.” That relationship is logarithmic.

The scoring idea

The algorithm assigns each revision a score based on its age, then keeps only one revision per score bucket. The score formula produces high, widely-spaced values for recent revisions and small, clustered values for old ones.

The core expression, simplified, looks like this:

(
  ln( EXTRACT(epoch FROM (now() - created_at)) )
  /
  ( EXTRACT(epoch FROM (now() - created_at)) / 6000 )
)
* ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
* 1000

Let s be the age in seconds. The formula is roughly ln(s) / s * C, where both the logarithm in the numerator and s in the denominator make the result decrease rapidly as s grows.

Cast to an integer, the effect is this: a revision saved 10 minutes ago might score 8432, one saved 11 minutes ago scores 8431. They’re in different buckets. A revision from six months ago scores 2, one from eight months ago also scores 2. Same bucket. The window function then picks the most recent revision from each bucket and discards the rest.

The result is automatic: recent saves are all kept because each has a distinct score; old saves are thinned because many share the same score.

The DQL attempt that didn’t ship

Window functions aren’t part of DQL. Doctrine’s query language has no syntax for OVER, PARTITION BY, or ROW_NUMBER(). Before going to raw SQL, the team tried to add them.

The FunctionNode approach works for single SQL functions, as we’d already seen with FTS. A RowNumber node emitting ROW_NUMBER() is trivial:

class RowNumber extends FunctionNode
{
    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'ROW_NUMBER()';
    }
}

The harder part is OVER(PARTITION BY ... ORDER BY ...). An Over function node was drafted, with a custom PartitionByClause AST node to handle the PARTITION BY clause:

class Over extends FunctionNode
{
    protected ?PartitionByClause $partitionByClause = null;
    protected ?OrderByClause $orderByClause = null;

    public function getSql(SqlWalker $sqlWalker): string
    {
        return 'OVER('
            .($this->partitionByClause
                ? $this->partitionByClause->dispatch($sqlWalker)
                : ($this->orderByClause
                    ? $this->orderByClause->dispatch($sqlWalker)
                    : ''))
            .')';
    }
}

It was never finished. The classes shipped marked @deprecated and “NOT TESTED YET”. The issue is composability: DQL’s FunctionNode works cleanly for functions that appear in WHERE clauses or SELECT expressions. A window function like ROW_NUMBER() OVER (PARTITION BY ...) is a different structure: it appears in a SELECT position, modifies the surrounding query semantics, and requires the parser to handle PARTITION BY as an extension to DQL’s grammar. Making that robust enough to trust in production is a significant investment. Going to DBAL and writing the SQL directly took an afternoon.

The query, layer by layer

The final implementation is three nested queries:

DELETE FROM revision
WHERE iri = ?
AND id NOT IN (
    SELECT id FROM (
        SELECT
            row_number() OVER (
                PARTITION BY num, iri
                ORDER BY num DESC, created_at DESC
            ) AS lines,
            *
        FROM (
            SELECT
                (
                    ( ln( EXTRACT(epoch FROM (now() - created_at)) )
                      / ( EXTRACT(epoch FROM (now() - created_at)) / 6000 ) )
                    * ( 1 / (EXTRACT(epoch FROM (now() - created_at)) / 60 / 1440) )
                    * 1000
                )::numeric::integer AS num,
                *
            FROM revision
            WHERE iri = ?
            ORDER BY created_at DESC
        ) AS lst
    ) AS rst
    WHERE lines = 1
);

Inner query: computes num, the integer score, for every revision of the given IRI. Rows are sorted by created_at DESC at this stage.

Middle query: runs ROW_NUMBER() OVER (PARTITION BY num, iri ORDER BY num DESC, created_at DESC). Within each score bucket (num), revisions are numbered starting from 1 in descending age order. The most recent revision in each bucket gets lines = 1.

Outer filter: keeps only the lines = 1 rows, one revision per score bucket.

DELETE: removes every revision for this IRI that isn’t in the kept set.

The PARTITION BY num, iri is redundant on the IRI (the whole query is already filtered to one IRI), but makes the intent explicit and keeps the logic correct if the query is ever reused in a broader context.

The method is called from a companion query that identifies which IRIs have accumulated more than a threshold of revisions:

public function getIrisWithMoreRevisionThan(int $maxRevisionsCount, int $limit = 0, ?int $retencyDay = null): array
{
    $queryBuilder = $this
        ->createQueryBuilder('revision')
        ->select('revision.iri')
        ->groupBy('revision.iri')
        ->having('COUNT(1) > :maxRevisions')
        ->orderBy('COUNT(1)', Order::Descending->value)
        ->setParameter('maxRevisions', $maxRevisionsCount);

    // ...

    return array_column($queryBuilder->getQuery()->getResult(), 'iri');
}

The two methods run together in a scheduled cleanup: find the IRIs over the threshold, prune each one.

Wiring it to a scheduled command

The pruning query doesn’t run in a request. It runs behind a Symfony command, called on a schedule.

The command takes a few options to control how aggressively it runs:

#[AsCommand('app:purge:revision', 'Remove useless revisions')]
final class PurgeRevisionCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addOption('max-revisions', 'm', InputOption::VALUE_REQUIRED,
                'Revision threshold above which an IRI gets pruned', 30)
            ->addOption('limit', 'l', InputOption::VALUE_REQUIRED,
                'Max number of IRIs to process per run')
            ->addOption('delay', 'w', InputOption::VALUE_REQUIRED,
                'Delay in seconds between each IRI')
            ->addOption('retencyDay', 'r', InputOption::VALUE_OPTIONAL,
                'Only process IRIs whose last revision is older than N days');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $iris = $this->revisionRepository->getIrisWithMoreRevisionThan(
            (int) $input->getOption('max-revisions'),
            (int) $input->getOption('limit'),
            (int) $input->getOption('retencyDay'),
        );

        foreach ($iris as $iri) {
            $totalDeleted += $this->revisionRepository->deleteOldRevisionForIri($iri);
            usleep((int) $input->getOption('delay') * 1_000_000);
        }

        return Command::SUCCESS;
    }
}

The --delay option is worth noting: on a busy database, hammering a hundred DELETE statements back-to-back can cause lock contention. A small sleep between iterations keeps the purge from competing with production traffic.

The command runs behind two crontab entries with different thresholds:

# Hourly: keep 30 revisions per IRI, process 100 IRIs per run
0 * * * * php bin/console app:purge:revision --max-revisions 30 --limit 100

# Nightly: for content untouched for a year, keep only 3
0 0 * * * php bin/console app:purge:revision --max-revisions 3 --limit 100 --retencyDay 365

The two-level strategy matters. The hourly job keeps 30 revisions per IRI, which is a reasonable ceiling for actively-edited content. The nightly job targets only IRIs not updated in over a year and keeps just 3. An article that hasn’t moved in twelve months doesn’t need thirty versions in its history.

What it looks like in practice

An article saved 200 times will typically keep 20 to 30 revisions after pruning: most of the recent saves, a handful from last month, one or two from each quarter of the previous year. The exact count depends on the age distribution of the saves, not on an arbitrary cap.

An article last edited two years ago might end up with 5 or 6 revisions. Recent edits are all there; the old history is compressed but not gone.

It’s not a perfect history. It’s a useful one.

The line between DQL and raw SQL

The window function attempt isn’t a failure worth hiding. It’s a useful data point: FunctionNode works well for scalar functions in WHERE and SELECT positions, but composing a full ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) expression in DQL is harder than it looks. The grammar extension, the AST nodes, the SQL walker integration: it’s a non-trivial amount of code for something that native SQL handles in three lines.

The practical boundary is roughly this: if a PostgreSQL feature maps to a function call with fixed arity, custom DQL works. If it requires new clause syntax (window frames, CTEs, lateral joins), native DBAL is usually the better trade-off.

The String component

PHP’s string handling is famously scattered: prefix-style functions here (str_), suffix-style there (strpos), inconsistent encoding support, and nothing object-oriented in sight. The String component wraps all of this into a fluent, unicode-aware object API:

use Symfony\Component\String\UnicodeString;

$str = new UnicodeString('  Hello World  ');
echo $str->trim()->lower()->replace(' ', '-'); // hello-world

The practical addition is the Slugger, a locale-aware slug generator that actually handles accented characters correctly:

$slug = $slugger->slug('L\'été à Montréal'); // l-ete-a-montreal

Before, you’d pull in a third-party library or write your own. Now it ships with FrameworkBundle, available by default.

Notifier

Email is handled by Mailer. SMS, push notifications, chat messages: no first-party story, until now. The Notifier component adds one: a unified interface over dozens of channels and providers.

The same notification can hit Slack, trigger an SMS via Twilio, or end up as a push notification, all configured through DSNs. Adding a new channel is a config change, not a code change.

Secrets vault

Storing secrets in .env files works, but the values are plain text, shared environments are a pain, and there’s no native way to encrypt anything at rest.

Symfony 5.0 adds a secrets: command family and a vault mechanism. Secrets are encrypted with a key pair stored outside the repository. The encrypted files get committed; the decrypt key does not. In production, the key comes in as an environment variable or gets injected from a secret manager.

php bin/console secrets:set DATABASE_PASSWORD
php bin/console secrets:decrypt-to-local --force

Not a full-blown secrets management solution, but a real step up from a plain .env file sitting unencrypted in your repo.

Mailer gets a notification layer

The Mailer component arrived in 4.4. What 5.0 adds on top is the NotificationEmail — a pre-styled, responsive email built on Foundation for Emails, with an explicit API for importance levels and call-to-action buttons:

use Symfony\Bridge\Twig\Mime\NotificationEmail;

$email = (new NotificationEmail())
    ->from('alerts@example.com')
    ->to('admin@example.com')
    ->subject('Disk usage critical')
    ->markdown('The disk on **prod-01** is at 94%. Check it now.')
    ->action('Open dashboard', 'https://example.com/servers')
    ->importance(NotificationEmail::IMPORTANCE_URGENT);

No template to write, no inline CSS to wrestle with. For transactional alerts, billing notifications, and system emails, it covers 80% of what you need without touching anything.

Lazy firewalls and the caching problem

Every stateful firewall in Symfony loads the user from session on every request, whether the action needs it or not. Which means any response is uncacheable by default, even for pages that never touch $this->getUser().

5.0 adds lazy mode for firewalls, which defers session access until the code actually calls is_granted() or reaches for the user token:

# config/packages/security.yaml
security:
    firewalls:
        main:
            pattern: ^/
            anonymous: lazy

Pages that don’t need the user become cacheable again. New projects get this by default via the Flex recipe; existing ones need a one-line config change.

Password migrations without the big bang

Migrating a live app from bcrypt to argon2id used to mean forcing a password reset on every user. The PasswordUpgraderInterface makes it gradual: at login, Symfony checks whether the stored hash matches the current algorithm. If not, it rehashes on the spot and calls your upgrader to save it:

// src/Repository/UserRepository.php
class UserRepository extends ServiceEntityRepository implements PasswordUpgraderInterface
{
    public function upgradePassword(UserInterface $user, string $newHashedPassword): void
    {
        $user->setPassword($newHashedPassword);
        $this->getEntityManager()->flush();
    }
}

Pair that with algorithm: auto in the encoder config, and old hashes migrate silently as users log in. No migration script, no downtime, no user friction.

ErrorHandler replaces Debug

The Debug component is gone. Its replacement, ErrorHandler, does the same job (converting PHP errors to exceptions, showing nice error pages) but without requiring Twig. For API apps that never render HTML, that matters: ErrorHandler generates errors in the format of the request (JSON, XML, plain text) following RFC 7807:

{
    "title": "Not Found",
    "status": 404,
    "detail": "Sorry, the page you are looking for could not be found"
}

The routing config moves from TwigBundle to FrameworkBundle, and that’s the only migration step for most projects. One line, done.

Event listeners, finally less verbose

Registering a kernel event listener used to mean explicitly naming the event in the service tag. Symfony 5.0 infers it from the method signature:

// No tag configuration needed beyond kernel.event_listener
final class SecurityListener
{
    public function onKernelRequest(RequestEvent $event): void
    {
        // Symfony reads the type hint and figures out the event
    }
}

# config/services.yaml
App\EventListener\SecurityListener:
    tags: [kernel.event_listener]

Use __invoke() and it works the same way. Bulk-register a whole directory of listeners with one resource block, and Symfony figures out which event each one handles.

HttpClient grows up

The HttpClient component arrived in 4.4 as stable. 5.0 adds a few useful things on top:

NTLM authentication for corporate environments, conditional buffering via a callback (buffer large responses only when the content-type matches), a max_duration option that caps the total request time regardless of network conditions, and toStream() to turn any response into a standard PHP stream for code that expects fread():

$response = $client->request('GET', 'https://api.example.com/large-export', [
    'max_duration' => 30.0,
    'buffer' => fn(array $headers): bool => str_contains($headers['content-type'][0] ?? '', 'json'),
]);

// Stream it instead of loading it all into memory
$stream = $response->toStream();

The client also got full interoperability with PSR-18 and HTTPlug v1/v2, so any library that depends on those abstractions just works with it.

What 5.0 removes

5.0 drops everything deprecated in 4.4. The most notable:

• WebServerBundle (use symfony server:start from the CLI tool instead)
• The old security system’s AnonymousToken (replaced by NullToken)
• Old form event names
• Symfony’s internal ClassLoader
• The Debug component (replaced by ErrorHandler)

If you ran your 4.4 app with deprecation notices active and fixed the warnings, upgrading to 5.0 requires no code changes.

The feature worth singling out arrived in 4.2 and matured through 4.3 and 4.4: HttpClient.

HttpClient

PHP’s built-in HTTP options (file_get_contents with stream contexts, cURL, Guzzle) each have their own model, their own quirks, and their own abstraction cost. Symfony 4.2 introduced HttpClient, a first-party HTTP client with one API over multiple transports.

The interface is clean:

$response = $client->request('GET', 'https://api.example.com/users');
$users = $response->toArray();

The implementation is async by default. Responses are lazy: the network request doesn’t happen until you actually read the response. Multiple requests can be initiated and resolved as data arrives, no threads or callbacks needed.

The built-in mock transport (MockHttpClient) makes testing HTTP calls painless without spinning up servers or patching global functions.

Mailer

Also stabilized in 4.4: the Mailer component, replacing SwiftMailerBundle as the recommended email solution. Transport is configured via DSN:

MAILER_DSN=smtp://user:pass@smtp.example.com:587

The DSN approach means switching providers (Mailgun, Postmark, SES, local SMTP) is a config change, not a code change. Email testing uses a spooler by default in non-production environments.

Messenger matures

The Messenger component landed in 3.4 as experimental. By 4.4 it’s stable and battle-tested: async message handling with retry logic, failure transport, and adapters for AMQP, Redis, Doctrine, and in-process transports.

The pattern it enables (handle a request synchronously, dispatch work asynchronously, retry on failure) replaces a class of Gearman/RabbitMQ setups that required separate libraries and significant configuration.

The LTS window

4.4 is supported for bugs until November 2022 and security fixes until November 2023. If you’re on 4.x and want stability, this is a comfortable place to land. The deprecation warnings it introduces point directly at what 5.0 will require.

The Messenger component, from experimental to production

Messenger arrived in 4.1 as an experiment. The concept was simple: dispatch a message object to a bus, handle it immediately or route it to a transport for async processing. By 4.3 and 4.4, the experiment had become infrastructure.

The 4.3 release added a dedicated failure transport. When a message fails after all retry attempts, it goes somewhere recoverable rather than just disappearing:

framework:
    messenger:
        failure_transport: failed
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
            failed: 'doctrine://default?queue_name=failed'
        routing:
            App\Message\SendEmail: async

Messages that land in failed can be inspected and retried manually. Before this, failed messages were a log entry and a headache. After this, they’re a queue you can actually work with.

Event dispatching, finally using objects properly

Since the beginning, Symfony’s event system used string event names as the primary identifier. You’d define OrderEvents::NEW_ORDER = 'order.new_order', listen on that string, and pass the event object as a secondary parameter.

4.3 flipped this around. The event object comes first, and the event name becomes optional:

// Before
$dispatcher->dispatch(OrderEvents::NEW_ORDER, $event);

// 4.3+
$dispatcher->dispatch($event);

Omit the name and Symfony uses the class name as the identifier. Listeners and subscribers can now reference the class directly:

public static function getSubscribedEvents(): array
{
    return [
        OrderPlacedEvent::class => 'onOrderPlaced',
    ];
}

The HttpKernel events were renamed accordingly: GetResponseEvent became RequestEvent, FilterResponseEvent became ResponseEvent. The old names stayed as aliases through 4.x.

VarDumper gets a server

dump() in a controller that returns JSON means your debug output gets injected straight into the response body. For API development, that’s annoying enough to make people disable dumping entirely.

4.1 added a VarDumper server that captures dumps separately:

bin/console server:dump

Configure the dump destination in config/packages/dev/debug.yaml:

debug:
    dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%"

Now dump() in your API controller sends data to the server’s console instead of polluting the response. The server shows the dump alongside its source file, the HTTP request that triggered it, and the timestamp.

VarExporter, for when var_export() fails you

var_export() has two problems: it ignores serialization semantics and its output isn’t PSR-2 compliant. The 4.2 VarExporter component fixes both.

$exported = VarExporter::export([123, ['abc', true]]);
// Returns:
// [
//     123,
//     [
//         'abc',
//         true,
//     ],
// ]

More importantly, it correctly handles objects implementing Serializable, __sleep, and __wakeup. Where var_export() silently drops serialization methods and exports raw properties, VarExporter produces code that calls the same hooks unserialize() would. The practical use case is cache warming: generating PHP files that can be loaded by OPcache without re-executing expensive computations.

Passwords that check against breach databases

The NotCompromisedPassword constraint arrived in 4.3. It checks submitted passwords against haveibeenpwned.com’s breach database without sending the actual password anywhere.

use Symfony\Component\Validator\Constraints as Assert;

class User
{
    #[Assert\NotCompromisedPassword]
    public string $plainPassword;
}

The implementation uses k-anonymity: SHA-1 hash the password, send only the first five characters to the API, get back all matching hashes, check locally. The password never leaves your server. For registration forms, adding this constraint is one line and a genuinely useful security signal.

Workflow gets context

The Workflow component existed before 4.x, but 4.3 added context propagation: the ability to pass arbitrary data through a transition and access it in listeners.

$workflow->apply($article, 'publish', [
    'user' => $user->getUsername(),
    'reason' => $request->request->get('reason'),
]);

The context arrives in TransitionEvent and gets stored alongside the marking. For audit trails, this is the difference between knowing a transition happened and knowing who triggered it and why. You can also inject context from a subscriber without touching every apply() call, which is handy for cross-cutting concerns like timestamps or current user.

The autowiring got smarter

4.2 added binding by type and name together. Before, you could bind by type (LoggerInterface) or by name ($logger), but not both at once. That caused problems when a service needs two different implementations of the same interface:

services:
    _defaults:
        bind:
            Psr\Log\LoggerInterface $orderLogger: '@monolog.logger.orders'
            Psr\Log\LoggerInterface $paymentLogger: '@monolog.logger.payments'

class OrderService
{
    public function __construct(
        private LoggerInterface $orderLogger,   // gets monolog.logger.orders
        private LoggerInterface $paymentLogger, // gets monolog.logger.payments
    ) {}
}

The match requires both type and argument name to align, so there’s no risk of accidentally injecting the wrong logger.

ErrorHandler replaces the Debug component

The Debug component, unchanged since 2013, had an awkward dependency on TwigBundle even for API-only apps. Any uncaught exception in a JSON API would render an HTML error page unless you wrote custom exception listeners.

4.4 extracts this into a dedicated ErrorHandler component. For non-HTML requests, error responses now follow RFC 7807 out of the box:

{
    "title": "Not Found",
    "status": 404,
    "detail": "Sorry, the page you are looking for could not be found"
}

No Twig required. The format follows the Accept header: JSON for JSON requests, XML for XML requests. To customize further, you provide a normalizer via the Serializer component rather than a Twig template.

PHP 7.4 preloading, wired in automatically

PHP 7.4 introduced OPcache preloading: load files into shared memory before any requests arrive, so they’re available as compiled opcodes from the very first request. The practical gain is 30-50% faster response times with no code changes.

The catch is configuration: you need to specify exactly which files to preload in php.ini. Symfony 4.4 generates that file automatically in the cache directory:

; php.ini
opcache.preload=/path/to/project/var/cache/prod/App_KernelProdContainer.preload.php
opcache.preload_user=www-data

Run cache:warmup in production and point OPcache at the generated file. Symfony preloads the container, compiled routes, and Twig templates: the files that are read on every request and never change between deploys.

Console: return codes and NO_COLOR

Two small things in 4.4 that honestly should have existed earlier. Commands that don’t return an integer from execute() now trigger a deprecation warning. In 5.0, the return type becomes mandatory. Returning 0 for success, non-zero for failure: standard Unix behavior, and it makes integration with process supervisors and CI pipelines unambiguous.

protected function execute(InputInterface $input, OutputInterface $output): int
{
    // ...
    return Command::SUCCESS; // = 0
}

The second: NO_COLOR environment variable support, following the convention from no-color.org. Set it and every Symfony console command drops ANSI escape codes regardless of what the terminal claims to support. Useful for CI environments that capture output as text and then choke on color codes embedded in logs.

4.0 is a different philosophy. The Symfony Standard Edition, the monolithic starting point that bundled everything and left you to remove what you didn’t need, is gone. In its place: a microframework that grows.

Flex

Symfony Flex is a Composer plugin that changes how you install Symfony packages. Before Flex, adding a bundle meant: install via Composer, register in AppKernel.php, add config to config/, update routing if needed. Four steps, all manual.

With Flex, installing a package runs a “recipe”: a set of automated steps that registers the bundle, generates a config skeleton, and wires routing. Installing Doctrine:

composer require symfony/orm-pack

That command installs the packages, creates config/packages/doctrine.yaml, adds the env variable stubs to .env, and registers everything. One command, zero manual steps.

Recipes are community-contributed and hosted on a central server. Quality varies, but for major packages they’re maintained alongside the packages themselves.

The new project structure

The Standard Edition layout (app/, src/, web/) is replaced by a leaner structure. Config lives in config/ split by environment. The public directory is now public/, not web/. The kernel is smaller. Controllers are plain classes, no extends Controller required.

More importantly, the default services.yaml uses the 3.3 autowiring defaults that make explicit service configuration mostly unnecessary. New projects start minimal and grow by adding what they actually need.

Services private by default

4.0’s biggest BC break for existing apps: all services are private by default. You can’t fetch a service from the container directly anymore, it has to be injected. This is the right call from a DI perspective, but it breaks anything that used $this->get('service_id') in controllers.

The migration path is AbstractController, which provides the same convenience methods through lazy service locators rather than raw container access.

What was removed

4.0 is clean because it removes everything deprecated in 3.4:

• The old form events, the old security interfaces, the old configuration formats
• Support for PHP < 7.1.3
• The ClassLoader component
• ACL support from SecurityBundle

The removals are aggressive. Apps that skipped fixing their 3.4 deprecations will have a rough time. Apps that did the cleanup beforehand have a smooth path.

Symfony 4.0 is the reset the framework needed. The Standard Edition had accumulated years of “this is how it’s done” that Flex sweeps away in one shot.

Environment variables that actually know their type

Before 3.4 and 4.0, environment variables were strings. Always. Trying to inject DATABASE_PORT into an int parameter would silently break or blow up with a type error. The fix was ugly: cast in PHP or avoid typed parameters entirely.

4.0 ships with env var processors that handle the conversion at the container level:

parameters:
    app.connection.port: '%env(int:DATABASE_PORT)%'
    app.debug_mode: '%env(bool:APP_DEBUG)%'

Beyond casting, processors can decode base64, load from files, parse JSON, or resolve container parameters within a value. The json:file: combination turned into a clean pattern for loading secrets from mounted files in containerized deployments:

parameters:
    env(SECRETS_FILE): '/run/secrets/app.json'
    app.secrets: '%env(json:file:SECRETS_FILE)%'

You can also write custom processors by implementing EnvVarProcessorInterface and tagging the service. Looks like overkill until the day you need it.

Tagged services without the boilerplate

Before 4.0, collecting all services with a given tag into one service meant writing a compiler pass. Forty lines of PHP to say “give me everything tagged app.handler.”

3.4 introduced the !tagged YAML shorthand, and 4.0 carries it forward:

services:
    App\HandlerCollection:
        arguments: [!tagged app.handler]

The collection is lazy by default when type-hinted as iterable, so services aren’t instantiated until you actually iterate. This replaced a whole category of compiler passes that existed for the sole purpose of building lists.

PHP as a configuration format

YAML has been the default for so long it feels required. It isn’t. 4.0 ships with PHP-based configuration using a fluent interface:

// config/services.php
return function (ContainerConfigurator $container) {
    $services = $container->services()
        ->defaults()
            ->autowire()
            ->autoconfigure();

    $services->load('App\\', '../src/')
        ->exclude('../src/{Entity,Repository}');
};

Same approach works for routes. The practical benefit: IDE autocompletion, type checking, and actual PHP logic in configuration without the % parameter interpolation syntax. YAML isn’t going anywhere, but now you have a choice.

Argon2i, because bcrypt was already aging

Symfony 3.4/4.0 added Argon2i support, winner of the 2015 Password Hashing Competition. Configuration is one line:

security:
    encoders:
        App\Entity\User:
            algorithm: argon2i

Argon2i is built into PHP 7.2+ and available via the sodium extension on earlier versions. Like bcrypt, it’s self-salting, no need to manage salt columns. Unlike bcrypt, it’s designed to resist GPU-based attacks with configurable memory usage. If you’re starting a new project on 4.0, there’s really no reason to reach for bcrypt.

The form layer gets a Bootstrap 4 theme

The existing Bootstrap 3 form theme has been around since Symfony 2.x. Bootstrap 4 ships as a first-class option in 4.0:

twig:
    form_themes: ['bootstrap_4_layout.html.twig']

More useful in practice: the tel and color HTML5 input types are now available as TelType and ColorType form types. Before, you had to write custom types or override raw widgets for those.

Local service binding

Global _defaults bindings apply to all services. Sometimes you need a binding scoped to a specific class or namespace, like different logger instances for different subsystems.

4.0 supports per-service bind for exactly that:

services:
    App\Service\OrderService:
        bind:
            Psr\Log\LoggerInterface: '@monolog.logger.orders'

    App\Service\PaymentService:
        bind:
            Psr\Log\LoggerInterface: '@monolog.logger.payments'

Same interface, two different implementations, no factory, no extra configuration. Small feature, but it kills a whole category of awkward workarounds.

3.4 is not a feature release. It ships with exactly the same features as 3.3, plus every deprecation warning that 4.0 will enforce. Its whole purpose is to be the migration tool: upgrade from 3.3 to 3.4, fix what’s in your logs, then step to 4.0 cleanly.

Why LTS releases matter in Symfony’s model

Symfony releases a new minor version every six months. That pace would be brutal for production apps to follow, so the project designates every fourth minor as an LTS: three years of bug fixes, four of security fixes. Which means teams can target 3.4 and mostly stop thinking about upgrades for a while.

3.4 is the last LTS of the 3.x line. If you’re still on 2.x or early 3.x, this is your landing zone.

The deprecation layer

Every feature that 4.0 removes is deprecated in 3.4. Run your app on 3.4 with deprecation notices enabled and your logs become a to-do list. The common ones:

• Services without explicit visibility (public/private) generate warnings — 4.0 makes all services private by default
• ControllerTrait is deprecated in favor of AbstractController
• The old security authenticator interfaces are marked for removal
• YAML-only service configuration without autowiring annotations triggers warnings

The intended workflow: upgrade to 3.4, run the test suite with deprecation notices as errors (SYMFONY_DEPRECATIONS_HELPER=max[self]=0 in PHPUnit), fix everything that fails. After that, the upgrade to 4.0 is basically mechanical.

The support window

3.4 LTS receives bug fixes until November 2020 and security fixes until November 2021. That’s a comfortable runway for apps that can’t follow every release. The cost: staying on the 3.x architecture, with no Flex, no micro-framework structure, no zero-config autowiring by default.

The bridge is there. Whether and when you cross it is a business decision, not a technical one.

Services go private

3.4 flipped the default visibility of services from public to private. Before this, $container->get('app.my_service') was perfectly normal code. After this, it’s an anti-pattern that generates a deprecation warning in 3.4 and breaks entirely in 4.0.

The reasoning is simple: fetching services directly from the container hides dependencies and defeats static analysis. If you inject through the constructor, the container can optimize the graph, tree-shake unused services, and catch mistakes at compile time. If you pull them at runtime, it can’t.

For apps already using autowiring, the migration is usually small. The sticky point is controllers that extend Controller and call $this->get('something'). The fix is switching to AbstractController, which provides the same shortcuts but through lazy service locators instead of raw container access.

For services that genuinely need to be public (accessed from legacy code or functional tests), mark them explicitly:

services:
    App\Service\LegacyAdapter:
        public: true

Binding scalar arguments once

A classic friction point with autowiring: scalar constructor arguments. If ten services all need $projectDir, you had to configure each one individually. The bind key under _defaults fixes that:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        bind:
            $projectDir: '%kernel.project_dir%'
            $mailerDsn: '%env(MAILER_DSN)%'
            Psr\Log\LoggerInterface $auditLogger: '@monolog.logger.audit'

Any service with a constructor parameter named $projectDir gets the bound value automatically. You can also bind by type-hint, which handles the common case where multiple logger channels exist and you need a specific one. Bindings in _defaults apply to all services in the file; you can override per-service if needed.

Injecting tagged services without a compiler pass

Before 3.4, collecting all services with a given tag meant writing a compiler pass. Now there’s a YAML shorthand:

services:
    App\Chain\TransformerChain:
        arguments:
            $transformers: !tagged app.transformer

class TransformerChain
{
    public function __construct(private iterable $transformers) {}
}

The !tagged notation creates an IteratorArgument: services are lazily instantiated as you iterate, so unused transformers never get built. For ordering, add a priority attribute to the tag definition on each service.

A logger that ships with the framework

No Monolog? No problem. Symfony 3.4 includes a PSR-3 logger that writes to php://stderr by default. Autowire it with Psr\Log\LoggerInterface:

use Psr\Log\LoggerInterface;

class MyService
{
    public function __construct(private LoggerInterface $logger) {}

    public function doSomething(): void
    {
        $this->logger->warning('Something questionable happened', ['context' => 'here']);
    }
}

The default minimum level is warning. The target is container and Kubernetes workloads where stderr is the natural log sink. It’s deliberately minimal: no handlers, no processors, no channels. When you need those, install Monolog.

Guard authenticators got a supports() method

The Guard component’s getCredentials() method was pulling double duty: deciding whether the authenticator should handle the request, and extracting the credentials. Returning null was the signal to skip. That made the contract messy.

3.4 added supports() to separate those concerns:

class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
    public function supports(Request $request): bool
    {
        return $request->headers->has('X-API-TOKEN');
    }

    public function getCredentials(Request $request): array
    {
        // Only called when supports() returns true.
        // Must always return credentials now.
        return ['token' => $request->headers->get('X-API-TOKEN')];
    }
}

The old GuardAuthenticatorInterface is deprecated. The practical benefit: base classes can implement shared getUser() and checkCredentials() logic, while subclasses only override supports() and getCredentials(). One responsibility each.

Two new debug commands

debug:autowiring replaces the old debug:container --types for discovering which type-hints work with autowiring:

$ bin/console debug:autowiring log

Autowirable Services
====================

  Psr\Log\LoggerInterface
      alias to monolog.logger
  Psr\Log\LoggerInterface $auditLogger
      alias to monolog.logger.audit

Pass a keyword to filter. No more guessing whether it’s LoggerInterface or Logger.

debug:form gives you the same introspection capability for form types:

$ bin/console debug:form App\Form\OrderType label_attr

Option: label_attr
  Required: false
  Default: []
  Allowed types: array

Without arguments it lists all registered form types, extensions, and guessers. With a type name and option name it shows every constraint on that option. Before this, you either read the source or trial-and-errored your way through.

Sessions got stricter by default

3.4 implements PHP 7.0’s SessionUpdateTimestampHandlerInterface, which brings two things: lazy session writes (only written when data actually changed) and strict session ID validation (IDs that don’t exist in the store are rejected rather than silently created, which blocks a class of session fixation attacks).

The old WriteCheckSessionHandler, NativeSessionHandler, and NativeProxy classes are deprecated. The MemcacheSessionHandler (note: not Memcached) is gone too, since the underlying PECL extension stopped receiving PHP 7 updates.

Twig form themes can now be scoped

Global form themes apply to every form in the app. If one form needs a completely different look, you had no clean way to opt out. The only keyword handles that:

{% raw %}{% form_theme orderForm with ['form/order_layout.html.twig'] only %}{% endraw %}

The only keyword disables all global themes for that form, including the base form_div_layout.html.twig. Your custom theme then needs to either provide all the blocks it uses, or explicitly pull them in with {% raw %}{% use 'form_div_layout.html.twig' %}{% endraw %}.

Overriding bundle templates without infinite loops

Overriding a bundle template that you also need to extend used to cause a circular reference error. Override @TwigBundle/Exception/error404.html.twig and also try to inherit from it? The old namespace resolution would follow your override and loop forever.

3.4 introduced the @! prefix to explicitly reference the original bundle template, bypassing any overrides:

{% raw %}{# templates/bundles/TwigBundle/Exception/error404.html.twig #}
{% extends '@!Twig/Exception/error404.html.twig' %}

{% block title %}Page not found{% endblock %}{% endraw %}

@TwigBundle resolves to your override if one exists. @!TwigBundle always resolves to the original. Override-and-extend, without the gymnastics.

The autowiring problem

Before 3.3, Symfony’s DI was powerful but verbose. Every service had to be declared explicitly in services.yml with its arguments listed. Autowiring existed since 3.1, but it was opt-in per service and had enough edge cases to bite you. Teams either wrote mountains of YAML or leaned on third-party bundles to cut the noise.

3.3 rewrote the defaults. With autoconfigure: true and autowire: true set once in the defaults section, every class in src/ becomes a service automatically, and its constructor dependencies are resolved by type. What used to take twenty lines of YAML now takes zero:

services:
    _defaults:
        autowire: true
        autoconfigure: true
    App\:
        resource: '../src/'