DEV Community: Arnaud POINTET

Encrypting columns with Symfony 8.2: what #[Encrypted] protects, and what it doesn't

Arnaud POINTET — Fri, 30 Oct 2026 07:47:49 +0000

Symfony 8.2 brings a new component, KeyManagement, still experimental. Its Doctrine bridge encrypts a column with an attribute, and an encrypted column can even stay searchable thanks to a blind index.

It takes very little code. But encrypting a column is not a box to tick: you need to know what you are protecting against, accept what the database will no longer be able to do, and plan for the day you encrypt a column that already holds data. This article works through those questions, using a table of patients as the example.

Two attributes

Encrypting a patient's phone number and date of birth comes down to two lines, one per column:

use Symfony\Component\KeyManagement\Bridge\DoctrineOrm\Attribute\Encrypted;

#[ORM\Column(nullable: true)]
#[Encrypted(key: 'patient.contact')]
private ?string $phone = null;

#[ORM\Column(type: Types::DATE\_IMMUTABLE, nullable: true)]
#[Encrypted(key: 'patient.identity')]
private ?\DateTimeImmutable $birthDate = null;

Doctrine writes an encrypted value to the database, and decrypts it when it reads the entity back. The property keeps its PHP type: the column's Doctrine type converts the value first (a date becomes text), then the result is encrypted. There is no Doctrine type to write and no listener to register: when the container is compiled, Symfony finds the marked properties and declares the types they need.

Encryption is randomized : the same value, encrypted twice, gives two different results. That is deliberate, otherwise comparing the column would be enough to tell which patients share a number. The flip side is that WHERE email = ? no longer finds anything. To find a patient by their encrypted email address, you add a blind index :

#[ORM\Column]
#[Encrypted(key: 'patient.contact')]
private string $email;

#[ORM\Column(length: 64)]
#[BlindIndexed('email', 'patient-email')]
private string $emailIndex = '';

The emailIndex column holds a keyed digest of the address: an HMAC-SHA256, computed under a subkey of its own, derived from the index's key and its name, patient-email. The same address always gives the same digest, but you need the key to compute it, and two indexes never give the same digest for the same value. A listener recomputes it on every flush() that inserts or updates the entity, and the lookup compares digests:

$this->findOneBy(['emailIndex' => $this->index->of($email)]);

What it protects against

Before encrypting anything, ask who you want to stop from reading. Column encryption protects against people who read the database without going through the application :

a backup left on poorly protected storage;
a copy of the production database on a developer's laptop, or in a staging environment;
an SQL injection that dumps the table: it gets encrypted bytes, not phone numbers;
read access to the database granted for support or reporting.

It does not protect against the application itself. The application has access to the keys, since it decrypts every time it loads an entity, and holds them in memory for the duration of a request. Someone who takes over the application server, or gets it to run their code, reads the data in clear, just as the application does. And once decrypted, a value is a string like any other: it ends up in the logs if you log the entity, in Sentry with an exception's stack trace, in a cache, in a CSV export or in a search engine. Encryption stops at the database; vigilance has to go further.

That leaves the question of the key. The component uses envelope encryption : each value is encrypted with a data key, which is itself encrypted with a master key that stays in a KMS (AWS KMS, Google Cloud KMS, Vault…). Without any particular configuration, each value carries its own encrypted data key, and every read and every write calls the KMS. With a key store (key_management.store), the encrypted data keys are kept in a table of the database: all the values of a scope (patient.contact) share one key, and the KMS is called once per key and per process. Without the master key, those stored keys are useless.

So where the master key lives decides how much protection you actually get. If the master key sits in the .env file, on the same server that also runs the database backups, someone who gets the whole server gets both. A local KMS with its key in the .env file is fine for development; in production, the master key lives somewhere other than the database, and ideally never leaves the KMS.

What the database can no longer do

An encrypted column is an opaque binary column. The database can no longer do anything with it, and that goes beyond WHERE:

No sorting, no partial search. No ORDER BY, no LIKE, no date comparison. That is why, in our patient table, the name stays in clear: the list is sorted by name, in SQL. Only encrypt what needs to be, and keep in mind that an encrypted date of birth no longer lets you look for "patients born before 1950".
No uniqueness constraint. Two identical addresses give two different encrypted values, so a UNIQUE index on the encrypted column never rejects anything. Put it on the blind index column instead: two identical addresses have the same digest there, as far as the projection is concerned (see below).
No length. The type declares an unbounded binary column (LONGBLOB, BYTEA…), whatever length the mapping says. That length describes the plaintext, and the encrypted result is longer.
A value is not bound to its row. The encryption does not know which row it is writing to. Someone who can write to the database can therefore copy one patient's encrypted phone number into the same column of another patient, and it will decrypt without error. If that risk matters to you, bind the value to its row yourself, for example by including the row's identifier in it and checking it after reading.

What the blind index reveals

A blind index does not reveal the addresses, but it does reveal something encryption was hiding: which rows share the same value , and how often each value occurs. For an email address, that is almost nothing, since nearly all addresses are different. For a column with few possible values, it is much worse: a blind index on country of birth or blood type shows the distribution at a glance, and knowing the value of a single row is enough to know the value of every row that carries the same digest. So only index varied values that are looked up by equality: an email address, a file number, a social security number.

Two other points are specific to the blind index.

Its key never changes. With a key store, the data key of an encrypted column is renewed on its own: after thirty days, the next write creates a new one, and the old ones stay readable. This is not hygiene: each value is encrypted with a random 96-bit nonce, and the standard (NIST SP 800-38D) caps a key at 2^32 encryptions in that case. The index key, on the other hand, must never be renewed: every digest already written was computed with it, and a new key would no longer find anyone. Changing that key means recomputing the whole column.

The projection decides what counts as equal. For an email address, you pick the Email projection, which normalizes the domain (its case, and the ASCII form of an internationalized domain) and ignores whitespace around the address: ada@Example.ORG and ada@example.org give the same digest. It leaves the part before the @ alone, since the standard says it is case-sensitive. If your application treats Ada@example.org and ada@example.org as the same person, normalize the address before saving it: the index compares what it is given.

Encrypting a column that already exists

On an empty database, adding the attribute is all it takes. In a real application, the phone column already holds thousands of numbers in clear, and that is where it gets tricky.

Adding #[Encrypted] changes the column's type: the migration Doctrine generates turns it into a binary column, but encrypts nothing. On PostgreSQL, it even fails as generated: you need to add USING phone::bytea (and USING birth_date::text::bytea for a date) for the database to accept the conversion. The numbers stay in clear, and on the first read, Doctrine rejects what it finds:

Doctrine\DBAL\Types\Exception\ValueNotConvertible:
Stored value is not a valid KeyManagement envelope.

Every row that is not encrypted makes loading its entity fail. And you cannot encrypt through the ORM: it cannot load those entities, and even if it could, it would see unchanged values and write nothing. You have to go through DBAL, asking Doctrine for the name of the type Symfony declared for the column:

use Doctrine\DBAL\ParameterType;
use Doctrine\DBAL\Types\Type;

$metadata = $entityManager->getClassMetadata(Patient::class);
$phone = Type::getType($metadata->getTypeOfField('phone'));
$connection = $entityManager->getConnection();
$platform = $connection->getDatabasePlatform();

foreach ($connection->iterateAssociative('SELECT id, phone FROM patient ORDER BY id') as $row) {
    $connection->update(
        'patient',
        ['phone' => $phone->convertToDatabaseValue($row['phone'], $platform)],
        ['id' => $row['id']],
        ['phone' => ParameterType::BINARY],
    );
}

getTypeOfField() returns the name of the type Symfony declared for that column (here encrypted_string@patient.contact), and that type encrypts exactly the way the application will. For a date, first rebuild the DateTimeImmutable from the stored string, for example with Type::getType('date_immutable')->convertToPHPValue(), then pass it to convertToDatabaseValue(), as the ORM would.

As written, this script is not idempotent: run again, it would encrypt the already encrypted rows a second time. To make it idempotent, skip the rows that Envelope::fromBytes() accepts: a plaintext value is never a valid envelope, and the method throws an exception on it. Finally, between the schema migration and the end of the script, every row that is not yet encrypted is unreadable. There are two ways to handle that.

A short maintenance window. Run the schema migration and the script back to back, with the application stopped. It is the simplest option. With a key store, where the KMS is called once per scope, a few hundred thousand rows are encrypted in a few minutes. Without one, each row costs a KMS call, which is slow and billed.
A parallel column. Add an encrypted column next to the old one; the application writes to both and reads the old one. A script fills the new one in batches, only touching the rows where it is empty. Then switch reads over, and drop the old column. It takes longer, but nothing stops.

Either way, don't forget the data that is not in the table: backups taken before the migration still hold the numbers in clear, and will for as long as they are kept.

The blind index has the same problem. The listener only computes a digest for the entities a flush() inserts or updates: rows that existed before the column was added keep an empty digest until they are modified, and no search finds them until then. So fill them once, with the same kind of script: read the address back with the encrypted type's convertToPHPValue(), then write $index->of() into the column. The same trap awaits any bulk UPDATE, in SQL or in DQL: it changes the address without changing the digest, and the search then returns a row that no longer has that address.

What I take away from it

#[Encrypted] handles the most technical part: sound encryption, data keys renewed on their own, a master key you can change without rewriting rows, and even move to another provider when the data keys are kept in a store. Writing all that by hand, with a home-made Doctrine type, was a source of mistakes.

But column encryption is still a design decision. It protects the database, not the application; it takes sorting, searching and uniqueness away from the database; and the blind index, which makes a column searchable again, reveals what encryption was hiding. Before adding the attribute, it is worth writing down who you are protecting against, where the master key lives, and how you will encrypt the data that is already there.

To try it without installing anything, two Practice exercises run in your browser: encrypted columns and blind index.

Sharing a Symfony project in a URL, without storing anything

Arnaud POINTET — Fri, 30 Oct 2026 07:30:42 +0000

"Can you show me your code?" On Slack, the answer is usually a forty-line paste, without the Twig template that goes with it, without the route, and with no way to run it. Whoever wants to help copies it all into a local project, notices a file is missing, and the conversation fizzles out.

I added a playground to apprendre.forelse.fr: a blank Symfony 8 or Laravel 13 project that runs in the browser. You edit a controller, the preview updates, and a "Share" button gives you a link. Whoever opens it gets the project as it is, ready to run.

The interesting part isn't the button, it's what isn't behind it: no database, no storage, no share ID. All the code travels in the URL. Here is how, and the two questions it raises: size, and security.

The project already runs in the browser

I described the mechanics in a previous article: PHP 8.4 compiled to WebAssembly, a real Symfony project with its vendor/, and a Service Worker serving the preview. The server only delivers static files.

The playground reuses exactly that machinery. To the platform, it's an exercise with no objective and no test: a starting project, a list of editable files, and that's it. The editor, the console (bin/console, php artisan) and the preview are the same as in the exercises.

That left one question: how do you hand your copy of the project to someone else?

Why not server-side storage

The classic answer, the one 3v4l and CodePen use, is to save the code and hand out a short ID: /s/a8Fk2. It's clean, but it has a cost:

a table that grows forever, full of content nobody moderates;
a GDPR question with every share, since the code can contain anything;
links that die the day you clean up.

For a learning playground, I wanted none of that. And the browser offers a perfect place to carry data without sending it to the server: the URL fragment , everything after the #.

The fragment, the part of the URL the server never sees

When you open https://apprendre.forelse.fr/en/playground/symfony#code=…, the browser asks the server for /en/playground/symfony and keeps the rest to itself. The fragment shows up neither in the HTTP request, nor in the server logs, nor in the Referer header. Only the page's JavaScript can read it, through location.hash.

That's exactly what's needed: the public page stays the same for everyone (one URL to index, one canonical), and the code only exists in the link and in the browsers of the people who open it.

One exception to watch: analytics. Some trackers send the full URL, fragment included. The site uses Umami, which has an option for that (tag simplified):

<script defer src="/mesure/traceur.js" data-website-id="…" data-exclude-hash="true"></script>

Without it, every visitor's code would have ended up in the stats.

Fitting a project in a link

A full Symfony project weighs several megabytes, vendor/ included. But everything that doesn't change is already known: it's the starting project, the same for everyone. So the link only carries the difference, that is the files changed or created.

export function changedFiles(current: Record<string, string>, starting: Record<string, string>): Record<string, string> {
    return Object.fromEntries(Object.entries(current).filter(([path, content]) => starting[path] !== content));
}

Those files are turned into JSON, compressed with deflate (the fflate library, already there to unpack the PHP environment), then encoded in base64url, the base64 variant that only uses URL-safe characters:

export function encodeFragment(files: Record<string, string>): string {
    const bytes = deflateSync(strToU8(JSON.stringify({ v: 1, files })), { level: 9 });
    let binary = '';
    for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
    return 'code=' + btoa(binary).replace(/\+/g, '-').replace(/\//g, '\_').replace(/=+$/, '');
}

The v: 1 costs a few bytes, but it will let the format change without breaking links already shared.

In practice, it's very reasonable. The starting project's controller and Twig template, slightly edited, come to about 1,500 characters. Compressed and encoded, the fragment is a little over 1,000 characters. PHP code compresses well: lots of repeated keywords, use statements and indentation.

One unexpected constraint came from Bluesky, which counts the whole URL in its 300 characters. A shared project quickly goes over: in that case the Bluesky button disappears, and you still have copy link, the phone's share sheet, and LinkedIn and X, which display a shortened address.

Reading a link you didn't write

Decoding needs more care, because anyone can craft a link. Three rules:

Cap the size, before and after decompression. A few kilobytes of deflate can inflate to hundreds of megabytes. The fragment is rejected beyond 200,000 characters, and decompression runs chunk by chunk, stopped as soon as the total exceeds 1 MB:

const inflate = new Inflate((chunk) => {
    size += chunk.length;
    if (size > MAX_BYTES) throw new RangeError('too-large');
    chunks.push(chunk);
});
inflate.push(bytes, true);

Reject paths that leave the project. A file named ../../etc/passwd or /root.php is ignored. It would be fairly harmless in PHP's in-memory file system, but there is no reason to accept it.

Only accept editable files. The link can only write where the visitor could write themselves: for Symfony, src/*/*.php and the Twig templates; for Laravel, the routes, the code under app/ and the Blade views. The framework configuration isn't part of it: a shared link has no business touching config/packages/security.yaml.

On opening, the link's code becomes the visitor's draft (replacing any they had left), and the fragment is removed from the address bar with history.replaceState. Otherwise, reloading the page would force the link's code back over the changes made since.

Running someone else's code

That was the first question I got: is it really reasonable to send someone a link that runs code in their browser?

Let's start with what's safe. PHP runs in a Web Worker, in WebAssembly, with no network access: the worker's Content Security Policy only allows fetching the environments and the site's own build files. It can't read the visitor's files or call an API. The HTML and JavaScript the project produces are shown in an iframe served from another origin , with no cookie and no access to the platform. It's the same isolation as for the exercises, where learners already run their own code.

But "isolated" doesn't mean "harmless". The page shown in the preview can look like anything: a fake login page, for instance. And an infinite loop can make the CPU spin.

So I chose to never automatically run code received through a link. The project loads and the code can be read in the editor, but the preview first shows a warning:

This link contains code written by someone else. Read it in the editor before running it. It runs isolated from this site, but the page it shows can imitate anything: never type a password into it.

The preview only starts when you click "Run this code". That one click is deliberate friction, and the right trade-off: someone sharing a bug wants it read, not run blindly.

One last security choice: the playground offers Symfony and Laravel, but not Nuxt, even though the platform can simulate it. In the Nuxt simulator, part of the code (the server/ routes) runs on the platform's origin. That's fine for your own code, not for a stranger's.

What I take away

The URL fragment is an underrated tool. It lets you share a complete state with no backend, no account and nothing kept, as long as the state stays reasonably small. For a code playground, that's exactly the case: you almost never share more than a few files.

The flip side is that a link becomes untrusted input like any other. Treat it like a form sent by a stranger: cap, filter, and ask before running.

You can try the Symfony playground or the Laravel playground, no account needed. And next time someone asks for your code on Slack, send the link.

The engine is open source (AGPL-3.0): the code from this article is on GitHub, in playground/src/app/scratch.ts and Playground.ts.

400 or 422? Designing validation errors for a Symfony API

Arnaud POINTET — Wed, 28 Oct 2026 00:00:00 +0000

Since Symfony 8.2, an uncaught ValidationFailedException no longer results in a 500 error: Symfony itself turns it into a 422 response, complete with the list of violations. The Practice exercise that showcases this change is mostly about deleting code.

But behind that deleted line lies a real design question, one I often see poorly settled in the APIs I audit: what should an API return when the request is invalid? Which HTTP status code, which format, and what information does the client need in order to react? This article starts from the exercise and works through the whole question.

The exercise: one line fewer

A registration controller validated an object by hand, then had to wrap the validation exception in an HTTP exception:

$violations = $validator->validate($registration);
if (\count($violations) > 0) {
    throw new UnprocessableEntityHttpException(
        'Invalid registration.',
        new ValidationFailedException($registration, $violations),
    );
}

Without that wrapper, the exception turned into a 500 error. Since Symfony 8.2, you just throw it:

if (\count($violations) > 0) {
    throw new ValidationFailedException($registration, $violations);
}

The response is then exactly the one #[MapRequestPayload] produces when validation fails:

{
    "type": "https://symfony.com/errors/validation",
    "title": "Validation Failed",
    "status": 422,
    "detail": "email: This value is not a valid email address.\nusername: This value is too short. It should have 2 characters or more.",
    "violations": [
        {
            "propertyPath": "email",
            "title": "This value is not a valid email address.",
            "template": "This value is not a valid email address.",
            "parameters": { "{{ value }}": "\"not-an-email\"" },
            "type": "urn:uuid:bd79c0ab-ddba-46cc-a703-a7a4b08de310"
        }
    ]
}

(Only the first violation is shown here; the one for the username follows the same pattern.)

Before going further, let's look at how Symfony gets there. You'll be able to use the same mechanism for your own exceptions.

How Symfony picks the HTTP status code for an exception

The ValidationFailedException class now carries an attribute:

#[WithHttpStatus(422)]
class ValidationFailedException extends RuntimeException

When an exception bubbles up to the kernel, Symfony's ErrorListener looks for this attribute (parent classes included). If it finds it, it wraps the exception in an HttpException with the right status code: exactly what the controller used to do by hand. Then, if the Serializer component is installed and the client expects JSON (an Accept: application/json header, or the json format on the route), the Serializer formats the error: its ProblemNormalizer notices that the original exception is a validation error and delegates the list of violations to the ConstraintViolationListNormalizer. Otherwise, the 422 is rendered as HTML, which is the first thing to check when "it doesn't work" with a plain curl.

The same attribute works for your domain exceptions:

#[WithHttpStatus(409)]
final class UsernameAlreadyTaken extends \DomainException
{
}

One detail tends to reassure hexagonal architecture purists: a PHP attribute creates no runtime dependency. As long as nobody reads the attributes through reflection, the WithHttpStatus class isn't even loaded. Your domain can carry the attribute without actually depending on HttpKernel. If you'd rather not write anything in the domain, configuration does the same thing from the outside:

# config/packages/framework.yaml
framework:
    exceptions:
        App\Domain\UsernameAlreadyTaken:
            status\_code: 409
            log\_level: info

400, 422, 409: a status code for each problem

The HTTP status code is the first thing a client reads, and often the only thing it reads automatically. So it has to say who needs to fix what.

400 Bad Request : the request can't be parsed, for instance malformed JSON. The client has a bug: a human has to fix the code that sends the request.
415 Unsupported Media Type : the Content-Type declares a format the API doesn't read. Same consequence: it's the client code that needs fixing.
422 Unprocessable Content : the request is readable and well formed, but its content is invalid. The email address isn't one, the username is too short. Often it's the end user who has to correct their input, and the client has to display the errors next to the right fields.
409 Conflict : the request is valid, but it conflicts with the current state of the resource. The username is already taken, the order has already shipped, the version being edited is no longer the latest.

422 comes from WebDAV, but it has been part of general HTTP semantics since RFC 9110. There's no reason to avoid it anymore.

Symfony already follows this distinction with #[MapRequestPayload]: an unsupported format gives a 415 and an unreadable JSON body a 400, whereas a field of the wrong type (a string where an integer is expected) or a failed constraint gives a 422, with the violations.

The username-already-taken case

"This username is already taken": 409 or 422? Both are defensible. I lean towards 422 with a violation on username , for a practical reason: the client displays this error exactly like the others, under the relevant field. That's what the UniqueEntity constraint from Symfony's Doctrine bridge does.

But then you have to think about the case the constraint can't see. Two simultaneous registrations with the same username both pass validation, then the second one hits the database's unique index. Left unhandled, that's a Doctrine UniqueConstraintViolationException, and therefore a 500. I convert it into a violation, so the client gets the same response in every case:

try {
    $this->entityManager->flush();
} catch (UniqueConstraintViolationException) {
    throw new ValidationFailedException($registration, new ConstraintViolationList([
        new ConstraintViolation(
            'This username is already taken.',
            'This username is already taken.',
            [],
            $registration,
            'username',
            $registration->username,
            code: UniqueEntity::NOT\_UNIQUE\_ERROR,
        ),
    ]));
}

The UniqueEntity::NOT_UNIQUE_ERROR code is not a detail: without it, the violation goes out with no type member, and the client loses the only stable marker it has (see below). And nothing else in that catch: after this exception, Doctrine has closed the EntityManager, so a second flush() would fail.

With Symfony 8.2, this conversion boils down to a single throw, with no HttpException around it.

The format: Problem Details

The JSON produced by Symfony follows the Problem Details for HTTP APIs format, standardized by RFC 9457 (which superseded RFC 7807). The format defines five standard members:

type: a URI that identifies the kind of problem. That's what the client should check, not the title;
title: a human-readable summary of that kind of problem, identical from one occurrence to the next;
status: the HTTP status code, repeated in the body;
detail: the explanation for this occurrence;
instance: a URI that identifies this specific occurrence, handy for tracking an error down in the logs.

Everything else, such as violations, is an extension member, which the standard explicitly provides for. Adopting this format lets clients use existing libraries rather than learn yet another home-grown format. The RFC also recommends the application/problem+json media type, which some clients use to detect an error. Symfony sets it automatically as soon as the body has a type, a title and a status; a hand-built error response has to remember to do so.

What the client actually needs

This is where most APIs fall short. They return errors written for a human reading the response, when it's a program that receives them.

A path that matches the request

propertyPath must point to the field as the client sent it. If your API receives snake_case and your DTOs use camelCase, the normalizer applies the name converter configured in the Serializer. The path becomes date_of_birth rather than dateOfBirth, provided that converter is properly configured. For a nested structure, the path takes the form addresses[0].postalCode, which lets the client find the offending row in a repeated form.

A stable code, not a message

A violation's title is a translated message: it changes with the language, and on the day someone fixes a typo in a translation file. A client that checks title === "This value is too short..." will break sooner or later.

The type member of each violation, on the other hand, is stable: urn:uuid: followed by the constraint's code. For example, Length::TOO_SHORT_ERROR and Email::INVALID_FORMAT_ERROR are UUIDs set in stone in Symfony's code. Yours should be too, if you write custom constraints: give them error constants with a UUID. That code is what the client should check to display its own message or trigger specific behavior.

Document these codes alongside your API (in your OpenAPI schema, for example). It's the most useful part of an error contract, and the one most often forgotten.

The useful data, and nothing more

The invalid value itself is not returned as such: ValidationFailedException::getValue() isn't serialized. Only the {{ value }} parameter of some messages echoes it. Keep that in mind for sensitive fields: a password rejected by a Regex constraint must not come back in plain text in the response, let alone in your logs.

In debug mode, the response also includes the exception class and the full stack trace. That's invaluable in development, and an information leak if APP_DEBUG stays on in production. This isn't hypothetical: I run into it regularly during audits.

Logging: a 422 is not an incident

Symfony logs 4xx HTTP errors at the warning level. That is in fact new in 8.2 for exceptions that get their status code through #[WithHttpStatus] or framework.exceptions, such as ValidationFailedException: before, they were logged at error, which triggered the fingers_crossed handler from the Monolog recipe. For a public API, validation errors are part of normal operation: thousands of incorrect inputs a day mean as many warning lines, and the real warnings get lost in the noise. I take them down one level:

framework:
    exceptions:
        Symfony\Component\Validator\Exception\ValidationFailedException:
            log\_level: info

On the other hand, I keep an alert on the rate of 422s per endpoint. A sudden spike after a deployment is often a mobile client that hasn't been updated, or a constraint that has become too strict. A single validation error is normal; a wave of them is an incident.

Test the contract, not the messages

The exercise's tests check what a client really expects: the 422 status code, the problem type and the list of fields in error.

$this->assertResponseStatusCodeSame(422);
$problem = json\_decode((string) $client->getResponse()->getContent(), true);
$this->assertSame('https://symfony.com/errors/validation', $problem['type']);
$this->assertSame(['email', 'username'], array\_column($problem['violations'], 'propertyPath'));

No test on the message text. If you want to go further, also check each violation's type: that's what belongs to the contract you've promised your clients.

My takeaways

The new feature in Symfony 8.2 is small: an exception that knows which HTTP status code it stands for. But it brings consistency where there was none: manual validation, #[MapRequestPayload] and the conversion of a database error now all go through the same path and produce the same response.

The rest is up to you: pick the right status code, stick to a standard format, give clients stable codes rather than sentences, and don't mistake invalid input for an incident.

The exercise takes a few minutes in the browser, on a development build of Symfony 8.2. The two requests in the "Requests" tab show the response before and after.

Two-factor authentication with Symfony 8.2: one authenticator, one voter, and that's it

Arnaud POINTET — Sun, 25 Oct 2026 00:00:00 +0000

Until now, two-factor authentication in Symfony meant either a bundle, scheb/2fa-bundle, or home-made code that worked around the firewall. The most common workaround looks like this: after the password, the user is logged in; a second authenticator checks the code and adds a role such as ROLE_2FA_SUCCEED to the token; a subscriber redirects users without that role to the code form.

It works, but it is fragile. The subscriber only protects the routes it is given, and any page you forget opens with the password alone. The role added to the token does not exist on the user: with an entity that does not implement EquatableInterface, as is the case with the one make:user generates, the ContextListener compares the roles of the refreshed user with those of the token, finds them different, and clears the token on the next request.

Symfony 8.2, expected at the end of November, makes this much simpler. The token now remembers how the user proved their identity, and a voter can ask the firewall for a new proof instead of answering 403. With these two building blocks, SMS two-factor authentication fits in an authenticator, a voter, an entry point, the service that sends the code and a few lines of security.yaml. The code in this article runs on the development version of Symfony 8.2, with functional tests.

The idea: two proofs, not a role

I introduced these features in Being logged in is not enough: asking for proof again before sensitive actions. In short: an authenticator states the method it checks with an AuthenticationMethodBadge (pwd, sms, otp…, the names from RFC 8176), and Symfony stores the method and the time on the token:

$token->getAuthenticationProofs();
// ['pwd' => 1793050000, 'sms' => 1793050042]

Here we use them for something else: not to protect one action, but the whole application, right from login.

The key point for two-factor authentication: when the same user authenticates a second time in the session, Symfony adds the new proof to those of the previous token instead of replacing them. That is exactly the two-factor flow: the password first, the code next, and a token that carries both.

form_login and json_login already state pwd. All that is left is to write the authenticator for the code, and to tell the firewall that protected pages require both proofs.

The configuration

# config/packages/security.yaml
security:
    firewalls:
        main:
            lazy: true
            provider: app_user_provider
            form_login:
                login_path: app_login
                check_path: app_login
                enable_csrf: true
            # The second factor: one more authenticator on the same firewall.
            custom_authenticators:
                - App\Security\SmsCodeAuthenticator
            # When the voter asks for a proof, this entry point decides which one.
            re_authentication_entry_point: App\Security\AskForMissingProof
            # Limits password and code attempts (symfony/rate-limiter component).
            login_throttling:
                max_attempts: 5
                interval: '15 minutes'
            logout:
                path: app_logout

    access_control:
        - { path: ^/login, roles: PUBLIC_ACCESS }
        - { path: ^/logout, roles: PUBLIC_ACCESS }
        - { path: ^/verify, roles: IS_AUTHENTICATED_FULLY }
        - { path: ^/, roles: TWO_FACTORS }

The last line does all the work: the whole application requires TWO_FACTORS, except login, logout and the code form. Protection is closed by default. A page added tomorrow is protected without anyone thinking about it.

The code form requires IS_AUTHENTICATED_FULLY, not PUBLIC_ACCESS: you must have given your password in this session to receive a code, a "remember me" cookie is not enough.

TWO_FACTORS is not a role: it is an attribute decided by a voter.

The voter: both proofs, or a new request

// src/Security/Voter/TwoFactorsVoter.php
namespace App\Security\Voter;

use App\Entity\User;
use Symfony\Component\Security\Core\Authentication\AuthenticationMethod;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Vote;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

final class TwoFactorsVoter extends Voter
{
    public const ATTRIBUTE = 'TWO_FACTORS';

    protected function supports(string $attribute, mixed $subject): bool
    {
        return self::ATTRIBUTE === $attribute;
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool
    {
        $proofs = $token->getAuthenticationProofs();

        if (isset($proofs[AuthenticationMethod::PASSWORD], $proofs[AuthenticationMethod::SMS])) {
            return true;
        }

        // A new proof only helps users who can provide one: without a phone, it's a 403.
        $user = $token->getUser();
        if ($user instanceof User && null !== $user->getPhoneNumber()) {
            $vote?->requestReAuthentication($attribute);
        }

        return false;
    }
}

$vote->requestReAuthentication() is the other new feature in 8.2. The voter denies access, but tells the firewall that a new authentication could change its answer. Instead of a 403, the firewall remembers the requested page and calls its re-authentication entry point.

The voter only does this for users who have a phone. For the others, a new form would lead nowhere: a 403 is more honest than a loop. In a real application, this is where you would send them to second-factor enrollment.

The entry point: asking for what is missing

// src/Security/AskForMissingProof.php
namespace App\Security;

use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\AuthenticationMethod;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Http\EntryPoint\ReAuthenticationEntryPointInterface;

final class AskForMissingProof implements ReAuthenticationEntryPointInterface
{
    public function __construct(
        private readonly UrlGeneratorInterface $urls,
    ) {
    }

    public function startReAuthentication(Request $request, TokenInterface $token): Response
    {
        // No password (session reopened by "remember me"): start with the password.
        $route = isset($token->getAuthenticationProofs()[AuthenticationMethod::PASSWORD])
            ? 'app_verify'
            : 'app_login';

        return new RedirectResponse($this->urls->generate($route));
    }
}

Without re_authentication_entry_point, the firewall would use the entry point of form_login, which can re-authenticate too: it would send the user to the login page, and they would type their password again without ever seeing the code form. Ours checks which proof is missing.

The "remember me" cookie is handled along the way: a session reopened by that cookie leaves no proof, Symfony explicitly excludes it. The voter therefore denies it, and the entry point sends the user to the password first.

The code authenticator

// src/Security/SmsCodeAuthenticator.php
namespace App\Security;

use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\AuthenticationMethod;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\InteractiveAuthenticatorInterface;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\AuthenticationMethodBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\CustomCredentials;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\SecurityRequestAttributes;
use Symfony\Component\Security\Http\Util\TargetPathTrait;

final class SmsCodeAuthenticator extends AbstractAuthenticator implements InteractiveAuthenticatorInterface
{
    use TargetPathTrait;

    public function __construct(
        private readonly Security $security,
        private readonly SmsCodes $codes,
        private readonly UrlGeneratorInterface $urls,
    ) {
    }

    public function supports(Request $request): ?bool
    {
        return $request->isMethod('POST') && 'app_verify' === $request->attributes->get('_route');
    }

    public function authenticate(Request $request): Passport
    {
        // The code completes the password: on its own, it logs nobody in.
        $user = $this->security->getUser()
            ?? throw new CustomUserMessageAuthenticationException('Log in with your password first.');

        return new Passport(
            new UserBadge($user->getUserIdentifier()),
            new CustomCredentials(
                fn (string $code): bool => $this->codes->verify($code),
                $request->getPayload()->getString('code'),
            ),
            [
                new CsrfTokenBadge('verify', $request->getPayload()->getString('_csrf_token')),
                new AuthenticationMethodBadge(AuthenticationMethod::SMS),
            ],
        );
    }

    // Only an interactive authentication leaves a proof on the token.
    public function isInteractive(): bool
    {
        return true;
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
    {
        $target = $this->getTargetPath($request->getSession(), $firewallName);
        $this->removeTargetPath($request->getSession(), $firewallName);

        return new RedirectResponse($target ?? $this->urls->generate('app_account'));
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $request->getSession()->set(SecurityRequestAttributes::AUTHENTICATION_ERROR, $exception);

        return new RedirectResponse($this->urls->generate('app_verify'));
    }
}

Three details matter:

InteractiveAuthenticatorInterface. Without it, the badge is ignored: Symfony only records proofs from an interactive authentication, one where the user has just done something. It is the most likely omission, and it raises no error: the code is accepted, but the sms proof never shows up, and the user is sent back to the form in a loop.
The user comes from the session. The authenticator does not read an identifier from the request: it reuses the one the password already authenticated. A code alone logs nobody in.
The passport has a UserBadge. That is what lets login_throttling count code attempts too: on the sixth attempt within fifteen minutes, even the right code is refused. Without a limit, a script eventually hits the right one among the million possible codes.

The code itself

The service that sends and checks the code has nothing specific to Symfony 8.2. It goes through the Notifier component (symfony/notifier), with your provider's SMS transport. The code is random, only its hash is kept in the session along with an expiry, and it can be used only once.

// src/Security/SmsCodes.php
namespace App\Security;

use App\Entity\User;
use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Notifier\Message\SmsMessage;
use Symfony\Component\Notifier\TexterInterface;

final class SmsCodes
{
    private const KEY = '_sms_code';
    private const LIFETIME = 300;

    public function __construct(
        private readonly TexterInterface $texter,
        private readonly RequestStack $requests,
    ) {
    }

    public function send(User $user): void
    {
        $code = sprintf('%06d', random_int(0, 999999));

        // In the session, only the hash of the code and its expiry.
        $this->requests->getSession()->set(self::KEY, [
            'hash' => hash('sha256', $code),
            'expires' => time() + self::LIFETIME,
        ]);

        $this->texter->send(new SmsMessage($user->getPhoneNumber(), "Your login code: $code"));
    }

    public function verify(string $code): bool
    {
        $session = $this->requests->getSession();
        $expected = $session->get(self::KEY);

        if (null === $expected || $expected['expires'] < time()) {
            return false;
        }

        if (!hash_equals($expected['hash'], hash('sha256', $code))) {
            return false;
        }

        $session->remove(self::KEY); // single use

        return true;
    }

    public function isPending(): bool
    {
        $expected = $this->requests->getSession()->get(self::KEY);

        return null !== $expected && $expected['expires'] >= time();
    }
}

The controller displays the form and only sends an SMS if no valid code is already pending. One SMS per page refresh means a growing bill, and an open door for anyone who wants to flood a phone number. For the same reason, a "Resend code" button should go through a rate limiter, for example one resend per minute.

// src/Controller/SecurityController.php (excerpt)
#[Route('/verify', name: 'app_verify', methods: ['GET', 'POST'])]
public function verify(
    #[CurrentUser] User $user,
    SmsCodes $codes,
    AuthenticationUtils $authenticationUtils,
): Response {
    // No phone, nothing to send: in a real application, redirect to enrollment.
    if (null === $user->getPhoneNumber()) {
        throw $this->createAccessDeniedException();
    }

    // The POST is handled by SmsCodeAuthenticator.
    if (!$codes->isPending()) {
        $codes->send($user);
    }

    return $this->render('security/verify.html.twig', [
        'error' => $authenticationUtils->getLastAuthenticationError(),
    ]);
}

The flow, end to end

Ada requests /account. She is not logged in: form_login sends her to /login.
She gives her password. The token carries pwd, and the firewall takes her back to /account.
The voter denies TWO_FACTORS and asks for a new proof. The firewall remembers /account, and the entry point sends her to /verify, which sends her a code.
She types the code. The token carries pwd and sms, and she is back on /account.

The voter does not look at the time of the proofs: once the code is given, it is valid for the whole session, as in most two-factor setups, and logging out clears everything. Since the time is stored, nothing stops you from requiring an sms proof less than 24 hours old.

No more subscriber, no more role added to the token, no more list of routes to keep up to date. The user keeps their usual roles, and an entity without EquatableInterface is not a problem: the tests of the example use a User class that does not implement it, and the session survives from one request to the next.

Before you adopt it

This article shows the mechanism, not a complete two-factor system. Three things to know.

SMS is one of the weakest second factors. It is exposed to SIM swapping, and NIST classifies it as a "restricted" authenticator. The same pattern works with an authenticator app: the authenticator checks a TOTP code with a library such as spomky-labs/otphp, states AuthenticationMethod::ONE_TIME_PASSWORD, and the voter requires otp instead of sms. You then need one secret per account, saved at enrollment after a first code is confirmed, and never shown again.

Enrollment and recovery are up to you. Registering the phone (or the TOTP secret), offering hashed, single-use backup codes, and protecting the deactivation of two-factor authentication with a recent proof. For that last point, IS_AUTHENTICATED_RECENTLY and the same re-authentication mechanism do the job: I covered it in Being logged in is not enough: asking for proof again before sensitive actions.

A limit of the mechanism. Re-authentication only kicks in when a single attribute is denied. An access_control rule that lists several attributes in roles always gives a 403: keep TWO_FACTORS alone on its line. Passing several attributes to the same decision is deprecated in 8.2 anyway.

If you want all of this ready to use, or cannot wait for Symfony 8.2, scheb/2fa-bundle is still the right choice: it brings TOTP, backup codes, trusted devices and codes by email. But if what you need is a second factor on an application you control, Symfony 8.2 lets you write it in under two hundred lines, without working around the firewall.

The CSRF token: what it protects, when you still need it, and how Symfony, Laravel, Django and Rails handle it

Arnaud POINTET — Sun, 25 Oct 2026 00:00:00 +0000

"The CSRF token is invalid. Please try to resubmit the form." in Symfony, "419 Page Expired" in Laravel, "CSRF verification failed. Request aborted." in Django: every web developer has run into one of these errors. The CSRF token is one of those protections everyone uses, because the framework turns it on by default, and few people can explain. In my audits I regularly find routes excluded from the check "because it was getting in the way", or, the other way round, Bearer token APIs that demand a CSRF token for nothing.

This article covers the whole question: what the token really protects, when it is still needed in the age of SameSite cookies, and how Symfony, Laravel, Django and Rails take care of it. Along the way, it explains a detail from a recent Practice exercise: why a simple search using the new HTTP QUERY method can be asked for a token.

The attack: making the victim's browser act

CSRF stands for Cross-Site Request Forgery. The attacker steals nothing. They get the victim's browser to send a request to a site where the victim is logged in.

Imagine you are logged in to your bank, and you then visit a booby-trapped page that contains this:

<form action="https://bank.example/transfer" method="POST" id="trap">
    <input type="hidden" name="iban" value="GB33 ... attacker's account">
    <input type="hidden" name="amount" value="2000">
</form>
<script>document.getElementById('trap').submit();</script>

The form submits itself to the bank. The browser attaches the bank's session cookie, as it does for any request to that domain. On the server side, nothing distinguishes this request from a genuine transfer: right session, right fields, right method.

That is the key point: the server recognises the user by a cookie that the browser sends on its own. As long as that is the case, any site can trigger actions on the user's behalf. The attacker cannot see the response, the same-origin policy prevents it, but they do not need to: the transfer is done.

What the token changes

The CSRF token is a random value that the server places in its own pages, usually in a hidden field, and requires on every submission. The attacker's site can build a form that targets the bank, but it cannot read a page from the bank to grab the token: the same-origin policy forbids it. Its request arrives without a valid token, and the server rejects it.

So the token does not protect you against an attacker who can run JavaScript on your own domain. An XSS flaw reads the token from the page just like your own code would. CSRF and XSS are two separate problems, and you cannot fix the first without fixing the second.

When do you need a token?

The rule fits in one sentence: any request that changes something, on an application that authenticates with a cookie.

Requests that change something : POST, PUT, PATCH, DELETE. Reads (GET, HEAD, OPTIONS) do not need one, provided they really change nothing. A deletion triggered by a GET link is protected by no framework at all: a simple <img src="https://site.example/dish/12/delete"> tag on another page is enough to trigger it.
Cookie authentication : a classic session, a "remember me" cookie, or an API token stored in a cookie. It is the automatic sending of the cookie that makes the attack possible.
The login form too. An attacker can log the victim in to the attacker's account, then collect whatever the victim enters there (an address, a saved card). This is login CSRF. Symfony covers it with the enable_csrf option of form_login.

Conversely, an API that authenticates with the Authorization: Bearer ... header does not need a CSRF token: another site cannot get the victim's browser to add that header. That is exactly why Laravel's api group does not check the token.

What about SameSite cookies?

A cookie's SameSite attribute tells the browser not to send it on requests coming from another site. With SameSite=Lax, the session cookie is no longer sent with the trap form's POST: the attack above fails, even without a token. Symfony and Laravel set SameSite=Lax on their session cookie by default. Chrome also applies a "Lax by default" rule to cookies that specify nothing, in a looser form: for two minutes after it is set, the cookie still goes along with a top-level POST. Firefox and Safari do not make that choice by default.

It is an excellent second line of defence, but I never leave it on its own:

Lax lets top-level GET navigations through. A link clicked on another site carries the cookie. An action triggered by GET therefore remains exposed.
"Same site" is not "same origin". blog.example.com and app.example.com are the same site as far as SameSite is concerned. A compromised subdomain, or one hosted by a third party, bypasses the protection.
Not every browser applies it to cookies that specify nothing , and a configuration change can disable it without anyone noticing, for example SameSite=None set to make an iframe integration work.

The case of the QUERY method

The HTTP QUERY method, standardised in 2026, is a read like GET, but with its criteria in the request body. Laravel 13.35 can route it, and the Practice exercise that introduces this feature includes a warning about the CSRF token. Laravel's CSRF middleware lets read methods (GET, HEAD, OPTIONS) through and checks all the others. QUERY is a read according to its RFC, but Laravel does not count it as one yet: declared in routes/web.php, a QUERY route requires a token, just like a POST. Since Laravel 13 there is a nuance: the middleware also accepts without a token a request that the browser marks as coming from the same origin (the Sec-Fetch-Site: same-origin header). A QUERY sent by your own pages over HTTPS therefore goes through; the 419 mostly shows up in local development over http, where the browser does not send that header.

Is forgetting a token a real risk here? Not really. An HTML form can only send GET and POST, and a QUERY request sent with fetch() from another site triggers a CORS preflight request, which your server rejects unless it allows that origin. The check adds nothing here, and it gets in the way. Hence the exercise's advice: a QUERY search belongs in routes/api.php.

How frameworks take care of it

The principle is the same everywhere. The differences come down to three points: where the token is stored, how it is sent, and what happens when it is missing.

Symfony

The Form component adds and checks the token on its own, in a hidden _token field. For a hand-written form, you generate the token with csrf_token('token_id') in Twig and check it with isCsrfTokenValid() in the controller, or with the #[IsCsrfTokenValid] attribute:

#[Route('/dish/{id}/delete', methods: ['POST'])]
#[IsCsrfTokenValid(new Expression('"delete-dish-" ~ args["dish"].getId()'), tokenKey: '\_token')]
public function delete(Dish $dish): Response

Historically, the token is stored in the session. Since Symfony 7.2, the symfony/form recipe enables stateless tokens for forms: instead of comparing the token with the session, Symfony checks that the Origin or Referer header matches the site's address, with a fallback cookie set by a small Stimulus controller. No session needs to be started just to display a form, which makes public pages easier to cache.

When the check fails, the form is not processed and carries the error "The CSRF token is invalid. Please try to resubmit the form."

Laravel

The PreventRequestForgery middleware (ValidateCsrfToken before Laravel 13) applies to the whole web group. Since Laravel 13, it first lets through requests marked Sec-Fetch-Site: same-origin (see the QUERY case above), then checks the token. In a Blade form, the @csrf directive adds the hidden _token field. For JavaScript calls, Laravel also accepts the token in the X-CSRF-TOKEN header, or in X-XSRF-TOKEN: Laravel sets an XSRF-TOKEN cookie that libraries such as Axios send back in that header automatically.

The token is stored in the session. When it is missing or does not match, Laravel responds with 419 Page Expired , a status code that does not exist in HTTP and that Laravel chose for this error. Exclusions are declared in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->preventRequestForgery(except: ['webhooks/stripe']);
})

Excluding a webhook is legitimate: it is not authenticated by a cookie, and it must have its own check, a signature. Excluding a route because it "was returning 419", on the other hand, almost always hides a forgotten @csrf or a lost session.

Django

The CsrfViewMiddleware middleware is enabled by default. In a template, {% csrf_token %} adds the hidden field. The token is stored in a csrftoken cookie (or in the session if you ask for it), and JavaScript sends it back in the X-CSRFToken header. Django also checks the Origin header, and over HTTPS the Referer: behind a proxy or with several domains, you have to declare the accepted origins in CSRF_TRUSTED_ORIGINS.

When the check fails, Django responds with a 403 and the "CSRF verification failed" page.

Rails

ApplicationController inherits the protection: protect_from_forgery is on by default, and raises an exception when the check fails. The csrf_meta_tags helper puts the token in the <head>, and the form helpers add it on their own. On the JavaScript side, Rails UJS or Turbo send it back in the X-CSRF-Token header.

When the check fails, Rails raises ActionController::InvalidAuthenticityToken, which results in a 422 response.

Summary

Framework	In the form	JavaScript header	On failure
Symfony	`_token` field (Form component, `csrf_token()`)	none by default (stateless tokens: handled by the Stimulus controller)	error on the form, or an exception when checked by hand
Laravel	`@csrf`	`X-CSRF-TOKEN` or `X-XSRF-TOKEN`	419 Page Expired
Django	`{% csrf_token %}`	`X-CSRFToken`	403
Rails	added by the form helpers	`X-CSRF-Token`	422

When the error hits a real user

Whatever the framework, the same causes come up when a legitimate user gets rejected:

The session has expired. The user left the tab open over lunch. It is the most common cause, and the only normal one: show a clear message and offer to resubmit the form.
The session cookie does not arrive. A misconfigured cookie domain, a Secure cookie on a site served over http, a cookie blocked by the browser.
The page is served from a cache. An HTTP cache hands out the same page, and therefore the same token, to everyone. Symfony's stateless tokens exist partly for this case.
Several servers do not share their sessions. The page comes from server A, the submission lands on server B, which does not know the token.
The proxy is not declared. The application thinks it is running over http while the browser announces https: every check that compares the origin fails (stateless Symfony, Django).

None of these causes is fixed by disabling the check.

What I take away from it

The CSRF token answers a precise problem: a browser that attaches an authentication cookie on its own to a request triggered by another site. Wherever that is not the case, such as a Bearer API or a method another site cannot send without CORS, it adds almost nothing. Wherever it is the case, it is still necessary, even with SameSite, which is only a second line of defence.

The exercise on the QUERY method takes a few minutes in the browser.

Being logged in is not enough: asking for proof again before sensitive actions

Arnaud POINTET — Sat, 24 Oct 2026 00:00:00 +0000

In most applications, authentication is a boolean. You are logged in or you are not, and once you are, everything is open: viewing your invoices, changing your email address, deleting your account, generating an API key.

Yet "logged in" covers very different situations. A session opened a minute ago with a password and a code. A session restored this morning by a "remember me" cookie set three weeks ago. A computer left unlocked over lunch. A session cookie stolen by a browser extension. To read a dashboard, the difference hardly matters. To change the address used to reset the password, it matters a lot.

GitHub asks for your password again before you delete your account or create an access token. Your bank asks for a code before a transfer to a new payee. This is called step-up authentication: you don't ask for everything all the time, but for an extra proof at the moment it counts.

Symfony 8.2 finally brings the building blocks to do it properly. But before the code come design choices, and they are what makes the difference.

Three questions instead of one

An authenticated session answers one question: who the user is. To decide whether they may perform a sensitive action, you need two more.

When did they last prove their identity? Not when the session started: when they last did something only they could do.
How did they prove it? A password, a code received by SMS, a security key, a magic link in their inbox.

These questions are not new. OpenID Connect has long answered them in the ID token: auth_time says when the user authenticated, amr (authentication methods references) lists the methods used, and the client can require a recent authentication with the max_age parameter. RFC 8176 standardizes the amr values: pwd for a password, sms, otp, hwk for a hardware key, and so on. If your application delegates login to an identity provider, a good part of this article is settled in that provider's configuration, and your application only has to read this information.

If your application does the authenticating, it is up to it to remember these answers.

Which actions to protect

Protecting everything amounts to protecting nothing: a user asked for their password every ten minutes ends up pasting it from a text file, or leaving the service. I sort actions with three criteria.

Does the action allow taking over the account? Changing the email address, the password, the phone number, disabling two-factor authentication, adding a security key. These are the top targets, because an attacker who succeeds once no longer needs the stolen session: they have the account. Changing the email is the most underestimated: it doesn't look like a security action, but it is the path password resets go through.

Is the action irreversible, or does it cost money? A transfer, an order, deleting an account or a project.

Does the action export data in bulk? A full export, creating an API key or an access token, adding a member with admin rights.

Everything else (browsing, editing a public profile, changing preferences) can usually make do with the session.

Two freshness levels are often enough. A proof less than a few hours old for sensitive pages to view, like invoices or login history. A proof a few minutes old for actions that hand over control of the account. The exact durations depend on your domain: a banking app does not have the same constraints as a project management tool.

Asking for the right proof

Asking for proof again, yes, but which one? Two mistakes come up often.

Asking for a weaker proof than the one used to log in. If the user logged in with a password and a security key, asking only for a code sent by email before disabling two-factor authentication opens a shortcut for anyone with access to their inbox. The proof you ask for must be at least as strong as the one the action lets you change or disable.

Believing all second factors are equal. SMS is still widespread, but it is exposed to SIM swapping: NIST classifies it as a "restricted" authenticator, to be used only knowingly and with an alternative offered to the user. GitHub, for instance, does not accept it for its sudo mode. An authenticator app (TOTP) or a security key (WebAuthn) is stronger. SMS is better than nothing, but that is no reason to make it the only safeguard for a large transfer.

And sometimes there is nothing to ask for: a user who never registered a phone cannot provide a code. Sending them to a form they cannot fill in leads nowhere. For them, a clear refusal, with instructions to add a second factor, is more honest than a dead end.

Don't break the flow

A successful re-authentication must take the user back exactly where they were going. Otherwise they start over, get tired, and rightly blame you for wasting their time.

A classic trap: protecting only the POST request that saves the form. The user fills in the address change form, submits it, gets sent to the password page… and their input is lost. Symfony's firewall, like most mechanisms of this kind, only remembers the target page for a read request (GET), excluding Ajax. It cannot replay a POST. The fix is simple: also protect the display of the form. The proof is requested before the user types anything, and it is still valid when they submit.

For an API, redirecting to a form makes no sense. RFC 9470 (OAuth 2.0 Step-Up Authentication Challenge Protocol) describes the expected response: a 401 with a WWW-Authenticate header carrying the insufficient_user_authentication error, and optionally max_age or acr_values to say what is missing. The client then knows it must start a stronger authentication, rather than display "access denied".

The re-authentication screen is a login screen

A page that only asks an already logged-in user for their password looks harmless. Yet it is exactly what someone who stole a session is looking for: a form to try passwords on, without having to guess the username. It therefore needs the same protections as a login form: attempt limiting, logging of failures, and one-time codes that expire quickly.

After a successful sensitive action, notify the user through another channel. An email saying "your address was changed", sent to the old address with a link to undo it, catches the case where every other protection was bypassed. It is the cheapest safety net in this article.

Finally, a session restored by a "remember me" cookie must never count as a recent proof. The cookie proves that a browser was logged in at some point, not that the person in front of the screen knows the password.

Before Symfony 8.2: a timestamp in the session

Up to Symfony 8.1, nothing is built in for the "when" or the "how". IS_AUTHENTICATED_FULLY only distinguishes a session opened by a form from one opened by the "remember me" cookie. So you have to record the time of the last proof yourself, for example in a LoginSuccessEvent listener:

#[AsEventListener]
public function \_\_invoke(LoginSuccessEvent $event): void
{
    // The "remember me" cookie triggers this event too: it proves nothing.
    if ($event->getAuthenticatedToken() instanceof RememberMeToken) {
        return;
    }

    $event->getRequest()->getSession()->set('last\_proof', time());
}

Then a voter compares this timestamp with the current time. It works, but everything is on you: recording the method as well as the time, redirecting to the right page instead of a 403, not forgetting the cookie case. It is exactly the kind of code you write once, halfway, and never read again.

What Symfony 8.2 brings

Symfony 8.2 (still in development as I write this) builds this mechanism into the Security component, in four pieces.

Freshness. Two new attributes, IS_AUTHENTICATED_RECENTLY (under two hours by default, the window of GitHub's sudo mode) and IS_AUTHENTICATED_VERY_RECENTLY (under five minutes), work wherever IS_AUTHENTICATED_FULLY does: #[IsGranted], access_control, Twig. The durations are set in security.yaml. A session opened by a "remember me" cookie fails both.

Re-authentication instead of refusal. When one of these attributes is denied, the firewall no longer responds with a 403: it remembers the requested page and calls a re-authentication entry point. form_login provides one, which redirects to the login page with the username already filled in. For a page that only asks for the password, you write your own by implementing ReAuthenticationEntryPointInterface, and declare it on the firewall with re_authentication_entry_point.

The "how". The token now records every method proven during the session, with the time it was last used, using the names from RFC 8176:

$token->getAuthenticationProofs();
// ['pwd' => 1792300000, 'sms' => 1792300060]

An authenticator declares its method with an AuthenticationMethodBadge on the passport. Only interactive authentications count, and the "remember me" cookie is explicitly excluded. An authenticator without a badge is recorded under the * method, unspecified. On the OpenID Connect side, the OIDC authenticator reads amr and auth_time from the ID token to feed these proofs. A voter can then require, for example, an sms proof less than five minutes old before a transfer.

Your own rules. A voter can tell the firewall that a new proof would change its answer, with $vote->requestReAuthentication($attribute). The entry point reads which attribute was denied and chooses what to ask for: a code for the transfer, the password for everything else. And the voter can also signal nothing, for the user who has no second factor: they keep their 403. One limit to know: the mechanism only kicks in when a single attribute is denied. A check combining several always yields a 403.

The when, the how and what to ask for again each have their answer in the framework. The choices remain yours: which actions to protect, with which proof, and for how long.

Try it

I turned these features into three exercises, to do in your browser, free and without an account, on a development build of Symfony 8.2:

Asking for the password again before sensitive pages, sudo mode;
Require an SMS code before a transfer, authentication proofs;
Ask for the right factor again instead of a 403, re-authentication from your voters.

PHP2Shell: how I patched my Symfony server

Arnaud POINTET — Thu, 22 Oct 2026 00:00:00 +0000

On the evening of 20 October, two critical flaws were disclosed in PHP: CVE-2026-109618 and CVE-2026-109619, quickly nicknamed "PHP2Shell". They allow unauthenticated remote code execution on the server, and are rated 9.2 out of 10. By the next morning, real-world attacks were already being reported.

These flaws are not in Symfony or Laravel, but in the PHP interpreter. No composer update fixes them: you have to change PHP itself. Here is how I did it for apprendre.forelse.fr, which runs on Symfony and FrankenPHP in Docker.

1. Know which PHP actually runs

First question: which version of PHP is serving requests? Not the one on my laptop, nor the one written in composer.json, but the one in the production container.

docker compose exec app php -v


PHP 8.4.26 (cli) (built: Oct 6 2026 01:25:42) (ZTS)

PHP 8.4.26: the latest version published at that point, and yet vulnerable. The fix did not exist yet.

My Dockerfile starts from dunglas/frankenphp:1-php8.4. That tag follows new releases of PHP 8.4, which gives the impression of always being up to date. It is not: the image is frozen at the moment it is built. Mine dated from 16 October. Until I rebuild it, it keeps the PHP from that day, even after FrankenPHP publishes a fixed image.

A floating tag (php8.4, latest) only gives you the latest version at the moment you rebuild the image.

2. A stopgap while waiting for the fix

The official fix was announced for 21 October at 14:00 UTC. In the meantime, I reduced the attack surface. Both flaws are memory issues. The first (CVE-2026-109618) is a memory corruption: a multipart request crafted to exhaust memory abruptly aborts request processing. The second (CVE-2026-109619) is a use-after-free between two requests served by the same worker. According to Rapid7's analysis, its first known trigger is upload progress tracking, session.upload_progress. It is enabled by default, and usable without even calling session_start().

My application does not use that tracking. So I turned it off in php.ini:

session.upload\_progress.enabled = Off

This file ships inside the image: the change only reaches production after a rebuild and a redeploy, like any other config. Then you check it was applied (in the FrankenPHP image, the CLI and the server read the same php.ini):

docker compose exec app php -i | grep upload_progress.enabled

This is not a fix. It closes the first known trigger of the second flaw, but not the memory corruption of the first. One unused option switched off is one less open door until the real fix is in.

3. Rebuild the image with the fixed PHP

The fix shipped on 21 October 2026: PHP 8.4.27 for my branch (and 8.2.35, 8.3.36, 8.5.12 for the others). FrankenPHP followed the same evening with its 1.13.2 release, whose images already bundle these fixed PHP versions.

My Dockerfile started from dunglas/frankenphp:1-php8.4, a floating tag. I took the opportunity to pin an exact version: dunglas/frankenphp:1.13.2-php8.5, which bundles PHP 8.5.12, fixed as well. To stay on PHP 8.4 without switching branches, 1.13.2-php8.4 gives you 8.4.27.

That leaves rebuilding the image. Since hosted CI runners are fresh every time, the FROM re-pulls the base image. But on a machine that already has an image cached, Docker would reuse it: to be safe, force a re-pull of the base image.

docker build --pull -t my-image .

In CI with docker/build-push-action, the equivalent is the pull: true option. The layer cache (cache-from) is not a problem here: its key depends on the base image's digest, which has changed, so every layer that builds on it is rebuilt.

Then redeploy, and check again:

docker compose exec app php -v

The version shown should now be 8.5.12. As long as it says 8.4.26, the old image is still running.

4. A safety net for next time

What bothered me most in this episode was not knowing right away that my production server was still running a vulnerable PHP. composer audit only looks at PHP dependencies, not the interpreter. So I added a safety net to my CI: when I cut a release (a tag), a job reads the PHP actually bundled in the image and compares it to the latest published version of its branch. If it is behind, the job raises a clearly visible warning on the release.

# PHP bundled in the image we are about to publish
installed=$(docker run --rm --entrypoint php "$IMAGE" -r 'echo PHP\_VERSION;')
branch=${installed%.\*} # 8.5.12 -> 8.5

# Latest published version of that branch, per php.net
latest=$(curl -fsS "https://www.php.net/releases/?json&version=${branch}&max=1" \
  | jq -r 'keys\_unsorted[0]')

if dpkg --compare-versions "$installed" lt "$latest"; then
  echo "::warning::PHP ${installed} is behind ${latest}, consider bumping the base image."
fi

I wired it so that it only runs when cutting a release, not on other builds. I chose a warning rather than a failure: being one patch behind should not stop me from shipping, but it must be visible. This is not protection against the flaws themselves: it is a reminder, at the right moment, that the base image has fallen behind. Paired with a tool that watches the base image (Renovate, Dependabot), the window between "a fixed PHP exists" and "my production runs it" closes on its own.

5. What I take away

Watch PHP, not just Composer. composer audit does not see flaws in the interpreter. Hence the CI safety net from section 4, which compares the image's PHP to the latest published version.
Rebuild regularly, and track the base image. An image you never rebuild quietly goes stale. And if you pin an exact base version, which is safer for reproducibility, you need a tool like Renovate or Dependabot to get notified of new versions.
Turn off what you don't use. session.upload_progress is enabled by default, while few applications use it.
Check inside the container. The only version that matters is the one php -v returns in production.

Sources

Event bursts: debounce, uniqueness or rate limiting, which should you use?

Arnaud POINTET — Wed, 21 Oct 2026 00:00:00 +0000

A product gets edited three times in ten seconds, because someone fixes a typo, then the price, then the photo. An application that reindexes the product in the search engine on every change does the same expensive work three times. And if it goes about it the wrong way, it also indexes the wrong version.

That's the topic of the Practice exercise on #[DebounceFor], an attribute that shipped with Laravel 13.26. The exercise starts from a listener guarded by ShouldBeUnique, which lets a subtle bug slip through, and fixes it with the new attribute. This article picks up from there, looks at how the mechanism works, then compares the different ways to absorb a burst.

The starting bug: unique, but stale

The listener in the exercise looks like something we write all the time:

class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique{
    public int $uniqueFor = 30;

    public function \_\_construct(private SearchIndex $index) {}

    public function uniqueId(ProductUpdated $event): string
    {
        return (string) $event->productId;
    }

    public function handle(ProductUpdated $event): void
    {
        $this->index->upsert($event->productId, $event->name);
    }
}

Three edits back to back, a single indexing run: the count test passes. But ShouldBeUnique takes a lock on the first dispatch and discards the ones that follow for as long as that lock exists, that is, until processing finishes or at most uniqueFor seconds. So it's the first event that gets processed, with the first name. The index shows "Keyboard" while the product has been called "Mechanical keyboard" for twenty seconds, and nothing is ever going to fix it.

ShouldBeUnique answers the question "is this work already scheduled?" Here, the real question is "what is the latest state to process?" Those are two different needs.

The fix: wait for the burst to end

#[DebounceFor(30)]
class UpdateSearchIndex implements ShouldQueue{
    public function \_\_construct(private SearchIndex $index) {}

    public function debounceId(ProductUpdated $event): string
    {
        return (string) $event->productId;
    }

    public function handle(ProductUpdated $event): void
    {
        $this->index->upsert($event->productId, $event->name);
    }
}

The term comes from electronics, where a physical button "bounces" and sends several signals for a single press. You wait for the signal to settle before reading it. Front-end developers know it well: it's the search box that only queries the server once you've stopped typing.

Laravel in fact refuses to let a listener be both debounced and ShouldBeUnique: it throws a LogicException. The two strategies are incompatible by design.

How it works

The source code is short and worth reading, because it sheds light on the mechanism's limits.

On every dispatch , Laravel writes a random token to the cache, under a key derived from the listener and the debounceId: the current "owner". The job is queued with a 30-second delay and carries that token with it. Watch out: if the listener already sets its own delay (withDelay() or #[Delay]), that delay takes precedence over the DebounceFor one, without any warning.
A new dispatch for the same product writes a new token to the cache, replacing the old one.
When a job comes due , the worker compares its token with the one in the cache. If they differ, a more recent dispatch exists: the job is deleted without running, and Laravel fires a JobDebounced event. Otherwise, the job runs.

The result: only the job from the last dispatch goes through, 30 seconds after it. This mechanism has several consequences.

Jobs are created, then thrown away

Debouncing doesn't save you anything on the queue: three edits still create three jobs, and the worker still dequeues three. What you save is the work : two of the three jobs stop after a single cache read. For indexing that costs a network call to Elasticsearch or Meilisearch, that's what matters most. But for an import of 50,000 products, that's still 50,000 jobs in the queue.

The cache becomes a coordination point

The whole decision rests on the cache. Across several servers, it has to be shared (Redis, Memcached, database): a file or array cache local to each machine would break the mechanism entirely. The listener can point to a cache store other than the default one with a debounceVia() method.

And if the key disappears from the cache (eviction under memory pressure, a Redis restart without persistence), Laravel chooses to run the job rather than lose it. That's the right call, but it means duplicate processing is still possible. Debouncing reduces duplicates; it doesn't rule them out.

The most common case isn't eviction, by the way: the token lives for ten times the window, and at least five minutes. If the queue falls further behind than that, the key expires before the jobs are dequeued, and all the jobs in the burst run. So a clogged queue, precisely on the day there are lots of edits, loses its debounce.

The last event gets processed, with the delay on top

Work starts at the earliest 30 seconds after the last edit. For a search index, that's acceptable. For a "your order has shipped" notification, much less so. Picking the window means trading off the number of runs you avoid against data freshness.

The continuous-stream trap: `maxWait`

Picture a product whose stock is updated every ten seconds by a warehouse. With a 30-second window, each update pushes back the previous one: the burst never ends, and the product is never reindexed.

That's what maxWait is for:

#[DebounceFor(30, maxWait: 120)]

Laravel records the time of the burst's first dispatch. If a dispatch arrives when 120 seconds have already passed, it's queued with no delay, and that counter resets to zero. The delay is therefore capped at roughly two minutes, with one caveat: maxWait guarantees a dispatch with no delay, not an execution. If the queue itself is lagging and a new dispatch comes in before the worker has picked up that job, its token gets replaced, and it's thrown away like the others. (Since Laravel 13.27, the maxWait window also resets when a debounced job runs.)

As soon as an event can arrive continuously, I add a maxWait. Without it, a debounce can indefinitely delay processing of a very active object, and that's often the most important object.

Process the state, not the event

There's one weakness left in the exercise's listener, which the exercise doesn't ask you to fix: it indexes the name carried by the event. As long as the last event processed really is the most recent one, all is well. But between a retry after an error, a duplicate job after a cache eviction and two workers draining the queue in a slightly different order, "the last event" is a shakier notion than it looks.

In production, I'd rather have the listener reload the current state:

public function handle(ProductUpdated $event): void
{
    $product = Product::find($event->productId);

    if ($product === null) {
        $this->index->remove($event->productId);

        return;
    }

    $this->index->upsert($product->id, $product->name);
}

The event no longer says "here's the new name", but "this product changed, go take a look". Processing becomes idempotent : running it twice, or out of order, produces the same index. Debouncing is then only there to save work, no longer to guarantee data correctness. That's a much more robust division of responsibilities.

A corollary: an event dispatched inside a database transaction must go out after the commit (ShouldDispatchAfterCommit on the event, or after_commit on the queue connection). Otherwise, the worker may reread the database before the change is visible. With a 30-second delay, that's unlikely, but a slow transaction is still possible, and hitting maxWait sends the job out with no delay. When dispatch is deferred until after the commit, Laravel also releases the debounce lock if the transaction is rolled back.

Debounce, uniqueness, rate limiting: the table

There are several related tools for absorbing a burst, and they don't answer the same question:

Tool	What it keeps	When to use it
`#[DebounceFor]`	the last dispatch, after a quiet period	syncing state that changes in bursts: search index, cache, export to a third-party service
`ShouldBeUnique`	the first dispatch; later ones are ignored until it's processed	work that doesn't depend on the event's payload: "recalculate the statistics", "regenerate the sitemap"
`ShouldBeUniqueUntilProcessing`	the first dispatch, but a new dispatch is let through as soon as processing starts	same as above, when a change made during processing must also be taken into account
`WithoutOverlapping` middleware	every dispatch, but never two at once for the same key	protecting a resource that can't handle concurrency
`RateLimited` middleware	every dispatch, spread out over time	staying within an external API's quota

A note on the third row: if the listener reloads the state from the database, as in the previous section, ShouldBeUniqueUntilProcessing becomes a credible alternative to debouncing, with no artificial delay. The first edit triggers processing right away. Later ones, if they arrive during that processing, trigger a new run that will reload the final state. The price: more runs than with a debounce, but no added latency.

When per-object debouncing is no longer enough

The debounceId groups dispatches for the same object. A hundred products edited at the same time by an import means a hundred indexing runs, even with a perfect debounce. Yet a search engine indexes a hundred documents in one go far better than one document a hundred times.

For that case, you have to change approach: each edit adds the product ID to a set (a Redis SADD, a table of products to reindex), and a single job, triggered on a schedule or itself debounced with a fixed key, drains the set and indexes in batches. You're no longer debouncing events, you're accumulating changes. It's more code, but it's what holds up under a massive import.

Testing a debounce

One last point, about how the exercise tests it. Queue::fake() would be useless here: it records dispatches without running them, whereas all the behavior happens at execution time. So the exercise's tests use a real queue (the database driver), move the clock forward and start a real worker:

foreach ($edits as [$productId, $name]) {
    ProductUpdated::dispatch($productId, $name);
    $this->travel(2)->seconds();
}
$this->travel(60)->seconds();
Artisan::call('queue:work', ['--stop-when-empty' => true, '--sleep' => 0]);

Then they check what the system produced: one indexing run per product, with the latest name. It's slower than a fake, but it's the only way to test what actually matters. In production, I also recommend listening for JobDebounced to count discarded jobs: if that counter stays at zero, the debounce is pointless. If it's very high, the window may be too long for your users.

My takeaways

#[DebounceFor] fixes a genuine misuse: we were using ShouldBeUnique to absorb bursts, and indexing the wrong version. The new attribute does what we actually wanted, in a few lines.

But a debounce is still an optimization, not a guarantee. It doesn't shrink the queue, it depends on the cache, it adds latency, and it lets duplicates through when the cache falters. Robustness comes from elsewhere: processing that reloads the state and can run twice without harm. The debounce then makes that processing cheaper.

The exercise runs in the browser, with a real Laravel 13 and a real queue: you see the ShouldBeUnique bug, then its fix.

Versioning a Symfony API without duplicating your classes

Arnaud POINTET — Fri, 16 Oct 2026 00:00:00 +0000

An API that ships a new version cannot drop the old one overnight. Partners, a mobile app that hasn't been updated, a script written two years ago: they all still read v1. The data is the same, but the field names and the shape of the response have changed.

With the Symfony Serializer, groups already chose which properties are output. They said nothing about what they are called. Symfony 8.2 (still in development) fills that gap: #[SerializedName] and #[SerializedPath] now accept a groups argument, and a new context option, ignored_groups, leaves a group out for a single response.

The Practice exercise that showcases these features is about deleting loops. This article takes a step back: how two versions used to be served, what the new approach changes, and the pitfalls to know before adopting it.

The starting point

A bookshop publishes its books in three places. v1, which partners still read, answers with a flat shape and its old names:

{ "isbn": "978-0-15-601219-5", "name": "The Little Prince", "price\_cents": 790 }

v2 renamed the title and nests the price with its currency:

{ "isbn": "978-0-15-601219-5", "title": "The Little Prince", "price": { "cents": 790, "currency": "EUR" } }

The back office reads the same shape as v2, plus the stock. The Livre class carries v1, v2 and internal groups, but only one way of naming each property.

How we did it until now

One class per version

The most explicit solution: a BookV1 and a BookV2, each with its own names, and a bit of code to map the entity to one or the other. Each version's contract can be read at a glance, and that is a real advantage.

The cost shows up over time. Every field added to v2 raises the question for v1. Every format fix happens in two places. And a third version multiplies all of it. For versions that differ by three field names, that is a lot of code to maintain.

A loop after the serializer

The most common solution, and the exercise's before it is fixed: serialize with the version's group, then patch the array.

$books = [];
foreach ($this->normalizer->normalize($this->catalogue->books(), 'json', ['groups' => 'v1']) as $book) {
    $books[] = [
        'isbn' => $book['isbn'],
        'name' => $book['title'],
        'price\_cents' => $book['price']['cents'],
    ];
}

It works, but the v1 contract now lives in a controller, far from the class it describes. The day someone adds a field to the v1 group, it doesn't come out: the loop doesn't know about it. And the loop only works one way. If v1 also accepts writes, you need a second loop, in reverse, for deserialization.

A custom normalizer or name converter

The most "Symfony" solution: a normalizer that decorates ObjectNormalizer for books in v1, or a name converter that renames according to the context. Renaming then works both ways, and it stays out of the controller.

In practice, I see these classes age badly. The name converter is global to the Serializer: it receives every property of every class, and has to check the class and the version itself. The decorated normalizer has to find its place among the others, and must not forget nested objects. That is a lot of infrastructure to express "in v1, title is called name".

What Symfony 8.2 changes

One name per group

Both attributes become repeatable and take a groups argument:

#[Groups(['v1', 'v2'])]
#[SerializedName('name', groups: 'v1')]
public readonly string $title,

#[Groups(['v1', 'v2'])]
#[SerializedName('price\_cents', groups: 'v1')]
#[SerializedPath('[price][cents]', groups: 'v2')]
public readonly int $priceInCents,

Serialized with the v1 group, the title comes out as name; with v2, it keeps its PHP name. The price comes out flat as price_cents in v1, and nested as price.cents in v2. Each version's contract is back on the class, and the controller shrinks to one line:

return new JsonResponse($this->normalizer->normalize($this->catalogue->books(), 'json', ['groups' => 'v1']));

The renaming also applies to deserialization: a v1 body that sends name does fill $title, with no second loop. YAML and XML configuration follow suit, with a serialized key and a <serialized> element.

Leaving a group out

The stock belongs to the v2 and internal groups. The back office serializes v2 and sees it; the public API serializes v2 too, and must not see it. Before 8.2, you needed an unset() afterwards, or an extra group on every other property. The AbstractNormalizer::IGNORED_GROUPS context option settles it:

$this->normalizer->normalize($this->catalogue->books(), 'json', [
    AbstractNormalizer::GROUPS => 'v2',
    AbstractNormalizer::IGNORED\_GROUPS => 'internal',
]);

A property that belongs to an ignored group is not output, even if it also belongs to a requested group. Exclusion wins. With a context builder, it's withIgnoredGroups('internal').

The pitfalls

The ungrouped name is the fallback

A #[SerializedName] without a groups argument applies to every group. Combined with a per-group name, it becomes the fallback: the group's name wins when that group is requested, otherwise the ungrouped name applies.

Handy, but it backfires quickly. In the exercise, the price started with an ungrouped #[SerializedPath('[price][cents]')]. Add a #[SerializedName('price_cents', groups: 'v1')] without touching the path, and v1 finds two answers: a name for its group, and a fallback path. When serializing, the path silently wins: the price stays under price.cents, and price_cents never appears. When deserializing, the Serializer refuses to choose and throws a LogicException ("Found SerializedName and SerializedPath attributes"). Either way, the path has to be tied to the v2 group only.

The silent case is the most dangerous one. My rule: as soon as a property has a name per group, I give a group to every one of its names and paths. The implicit fallback is the first thing you overlook when rereading the class.

Several groups requested: the declaration decides

What happens if you request ['v1', 'v2'] and the property has a name for each? The first declared name whose group is requested wins. The order of the groups in the context doesn't matter. This is deliberate, so that two controllers listing the groups in a different order get the same response. But it means you can't pick a version by putting its group in front of the others. One response is one version, so one version group.

A property without a group disappears

This isn't new, but it gets rediscovered every time groups are introduced: as soon as the context requests groups, a property without #[Groups] is no longer output. Symfony 8.2 adds an option to get around this without annotating the whole class: with AbstractNormalizer::ENABLE_DEFAULT_GROUPS, ungrouped properties join the Default group and the class's short name (Livre), provided you request one of them in the context, for example ['v1', 'Default'].

`ignored_groups` is not `#[Ignore]`

Both remove properties, but not in the same place:

#[Ignore] sits on the property, in the class. The property is never output, anywhere, and never read in.
ignored_groups is passed in the context. It only applies to that call: the back office, which doesn't pass it, still sees the stock.
ignored_attributes, which has been around for a long time, removes properties by name. It works, but every controller has to know the list, and a property added to the internal group later won't be left out. With ignored_groups, the decision stays on the class.

One detail that matters for an API: the exclusion also applies to deserialization. A stock sent by a public API client is ignored, like an unknown key. Be careful if the property is a required constructor argument, as in the exercise: deserialization then fails for lack of a value. Give it a default value, or keep that property out of the constructor.

Test the contract on the response

The risk with these attributes is that a change to the class alters a version without anyone noticing. So I test each version against the exact response, not against the presence of a few keys:

$this->assertSame(
    ['isbn' => '978-0-15-601219-5', 'name' => 'The Little Prince', 'price\_cents' => 790],
    $this->fetch('/api/v1/books')[0],
);

An assertSame on the whole array fails if a field appears, disappears or gets renamed. That is exactly what a v1 partner would notice. The exercise's tests do the same for v2 and the back office.

When to keep two classes

Per-group names fit when the versions share the same model and only differ in shape: names, nesting, a few fields more or less. That is the most common case, and it's where the new feature removes the most code.

I keep separate classes when the versions diverge in substance: a field computed differently, a resource split in two, validation that is no longer the same. Stacking attributes for each version on a single property then becomes unreadable, and a dedicated class becomes the clear solution again. A good indicator: if a property carries more than two different names, the question is worth asking.

My takeaway

Symfony 8.2 doesn't change how to think about groups; it completes what they could do. A group already chose a version's fields; now it also gives their names and shape. And ignored_groups replaces the unset() calls lingering in controllers. Each version's contract goes back on the class it describes, and it holds both ways.

The exercise takes a few minutes in the browser, on a development version of Symfony 8.2. The three requests in the "Requests" tab must respond exactly as before, without a single loop in the controller.

Migrating files with zero downtime: what read-through does, and what it doesn't

Arnaud POINTET — Wed, 14 Oct 2026 00:00:00 +0000

Laravel 13.26 added a read-through disk driver. In the Practice exercise that introduces it, a controller serves documents in the middle of a migration: it reads from the new storage, falls back to the old one, and copies files over along the way. The driver replaces those fifteen lines with three lines of configuration.

That's good news, but a storage migration is more than that configuration. I've run several of them (local disk to S3, one bucket to another, one provider to another), and falling back on read is only one part of the job. This article starts from the exercise and goes all the way to the day you switch off the old storage.

The exercise: three lines of configuration

Before, the controller did everything itself:

$new = Storage::disk('new');
if ($new->exists($name)) {
    return $this->asText($new->get($name));
}

$old = Storage::disk('old');
if ($old->exists($name)) {
    $contents = $old->get($name);
    $new->put($name, $contents);

    return $this->asText($contents);
}

abort(404);

With Laravel 13.26, you declare a disk that combines the two:

// config/filesystems.php
'documents' => [
    'driver' => 'read-through',
    'primary' => 'new',
    'fallback' => 'old',
],

And the controller only knows about that one:

$documents = Storage::disk('documents');
abort_unless($documents->exists($name), 404);

return $this->asText($documents->get($name));

The win goes beyond fewer lines of code: the migration becomes a configuration detail, invisible to the rest of the application. The day it's over, you replace documents with a plain S3 disk, and not a single call to Storage::disk('documents') has to change.

What the driver actually does

The documentation is brief. The source code tells you more, and these details matter for what follows (the main operations, as of Laravel 13.26; move() and copy() on a file still sitting on the old disk only gained support in 13.27):

Operation	Behavior
`get()`, `readStream()`	reads `primary`; otherwise reads `fallback`, then writes a copy to `primary`
`exists()`	true if the file is on either disk
`put()`, `writeStream()`	writes to `primary` only
`delete()`	deletes from both disks
`files()`, `allFiles()`	list `primary` only
`url()`, `size()`, `mimeType()`, `lastModified()`	read from whichever disk has the file, without copying it

Two design choices are particularly well thought out.

Deletes hit both disks. Otherwise, a file deleted from the new storage would linger on the old one, and the next read would bring it back. It's the classic bug in hand-rolled fallbacks, and I've seen it reach production: documents deleted at a customer's request (including GDPR erasure requests) that were back the next day.

The copy re-checks before writing. Between the moment the driver finds the file missing from primary and the moment it copies it over, another request may have written a newer version. The driver checks again just before copying so it doesn't overwrite it. The race window doesn't disappear entirely (two operations are never atomic on object storage), but it becomes very narrow.

What read-through doesn't migrate

The driver migrates what the application reads. Everything else stays on the old disk, and that's where migrations get bogged down.

Files nobody ever reads

An invoice from 2019, an inactive user's avatar, a forgotten attachment: most of an application's files are almost never read again. Read-through quickly migrates the hot files, then plateaus. It can happen that after three months only 20% of the files have moved, and the old storage is still indispensable.

So you always need a bulk backfill (see below). Read-through doesn't replace the copy: it lets you do it at your own pace, with no maintenance window, while the application is already running on the new storage.

Files served by URL

This is the most common trap. On S3, you rarely serve a file by reading it with PHP: you generate a URL, possibly a signed one, and the browser downloads straight from the bucket.

$documents->temporaryUrl($name, now()->addMinutes(5));

The driver does return a working URL: the one for the disk that holds the file. But it doesn't read the file, so it never copies it. An application that serves all its files by URL migrates nothing at all with read-through, even though everything appears to work.

Listings

files() and allFiles() only list the new disk. So during the migration, an "All your documents" page that lists a folder only shows the documents already migrated. An export, a disk-usage calculation, a cleanup of orphaned files: anything that enumerates instead of reading a known path gives the wrong result.

If the application lists files, the right answer often isn't a technical one: the database should know which files exist, not the storage. A migration is when that debt comes due.

Metadata

The copy is a plain write(). For readStream(), the driver first buffers the whole file (in memory up to 2 MB, then in a temporary file) before writing it to the new disk and handing it back to you: so the first Storage::download() of a large unmigrated file waits for the copy to finish before sending the first byte. The modification date becomes the date of the copy. Visibility (public or private) and HTTP headers (Content-Type, Cache-Control, Content-Disposition) take the new disk's defaults. If your application relies on lastModified() for HTTP caching, or on S3 headers set at upload time, check this before you migrate. It's not a flaw in the driver: it's true of almost any file copy.

Failed copies

By default, if copying to the new disk fails (insufficient permissions, quota reached), the driver still returns the content it read from the old one. That's the right call for the user, who gets their file. But it means a migration can stall without making a sound. The driver accepts a throw_on_promotion_failure option to throw an exception in that case. Failing that, keep an eye on the volume of reads served by the old disk: if it isn't going down, something is stuck.

Seeing the migration through

Here is the plan I follow, and read-through is only one step of it.

1. Write to the new disk, read from both

You switch the application over to the read-through disk. From that point on, every new or modified file goes straight to the new storage, and the old one no longer receives any writes. That's the real cutover , and it happens with zero downtime.

If several applications or several servers write to the old storage, they all have to switch before you move on to the next step. Otherwise, files keep landing on the old disk after the backfill has already gone past.

2. Backfill the rest in the background

A command walks the old disk and copies whatever is missing. It must be able to stop and resume without starting over, and never overwrite a newer version:

final class BackfillDocuments extends Command
{
    protected $signature = 'documents:backfill';

    public function handle(): int
    {
        $old = Storage::disk('old');
        $new = Storage::disk('new');
        $copied = $failures = 0;

        foreach ($old->allFiles() as $path) {
            if ($new->exists($path)) {
                continue; // already migrated, or rewritten since: leave it alone
            }
            $stream = $old->readStream($path);
            $ok = null !== $stream && $new->writeStream($path, $stream);
            if (\is_resource($stream)) {
                fclose($stream);
            }
            if (!$ok) {
                $this->error("Failed: $path");
                ++$failures;
                continue;
            }
            ++$copied;
        }

        $this->info("$copied document(s) copied, $failures failure(s).");

        return $failures ? self::FAILURE : self::SUCCESS;
    }
}

The exists() check before each copy makes the command idempotent : rerunning it after an interruption only copies what's missing. Streaming (readStream()) keeps memory usage flat, even for files of several hundred megabytes. Failures are counted separately: without the 'throw' => true option on the disks, readStream() returns null and writeStream() returns false, with no exception, and a command that doesn't check them would report success.

With millions of files, allFiles() becomes a problem in its own right: it loads the entire list into memory. At that point you're better off walking the table that references the files, in batches (chunkById()), or spreading the work across a queue, one job per prefix or per batch of IDs.

3. Verify

Before switching anything off, I check that the old storage is contained in the new one: every file from the old storage exists on the new one, with the same size, and for a sample, the same checksum (md5, or the ETag on S3 for files uploaded in a single part). Comparing total file counts would be meaningless: the new disk has received every file written since the migration started, and a delete removed the file from both sides. This is also the time to check the metadata that matters to the application.

4. Unplug the fallback, keep the old storage

The documents disk goes back to being a plain S3 disk. If you want to play it safe, there's an intermediate step: keep the read-through disk with the 'copy' => false option. The fallback still serves the odd forgotten file but no longer writes anything, and a rise in reads from the old storage points to a gap in the backfill. The old storage itself stays in place for a few weeks, read-only. If a file is missing, you can still recover it. Keep a close eye on 404 logs for documents during this period.

5. Switch it off

Only now. It's often the step people forget, and the old bucket is still being billed two years later.

The hidden cost of 404s

One last detail, which matters on storage billed per request: a missing file now costs two checks, one on each disk. If your application gets a lot of requests for files that don't exist (bots, old links, thumbnails not generated yet), the number of requests to your storage doubles for the entire migration. One more reason not to let it drag on.

My takeaways

The read-through driver cleanly solves the trickiest part of a migration: cutting over with zero downtime, without any business code knowing a migration is underway. Its design choices (deleting from both disks, re-checking before copying) show that its authors have done this kind of migration before.

But a migration doesn't finish on its own. Read-through is step 1 of 5. What makes the difference is the idempotent backfill, the verification, and the discipline to actually switch off the old storage.

To see the driver in action, the Practice exercise runs in the browser, with nothing to install: a real Laravel 13, two disks, and tests that check every behavior.

DEV Community: Arnaud POINTET

Encrypting columns with Symfony 8.2: what #[Encrypted] protects, and what it doesn't

Two attributes

What it protects against

What the database can no longer do

What the blind index reveals

Encrypting a column that already exists

What I take away from it

Sharing a Symfony project in a URL, without storing anything

The project already runs in the browser

Why not server-side storage

The fragment, the part of the URL the server never sees

Fitting a project in a link

Reading a link you didn't write

Running someone else's code

What I take away

400 or 422? Designing validation errors for a Symfony API

The exercise: one line fewer

How Symfony picks the HTTP status code for an exception

400, 422, 409: a status code for each problem

The username-already-taken case

The format: Problem Details

What the client actually needs

A path that matches the request

A stable code, not a message

The useful data, and nothing more

Logging: a 422 is not an incident

Test the contract, not the messages

My takeaways

Two-factor authentication with Symfony 8.2: one authenticator, one voter, and that's it

The idea: two proofs, not a role

The configuration

The voter: both proofs, or a new request

The entry point: asking for what is missing

The code authenticator

The code itself

The flow, end to end

Before you adopt it

The CSRF token: what it protects, when you still need it, and how Symfony, Laravel, Django and Rails handle it

The attack: making the victim's browser act

What the token changes

When do you need a token?

What about SameSite cookies?

The case of the QUERY method

How frameworks take care of it

Symfony

Laravel

Django

Rails

Summary

When the error hits a real user

What I take away from it

Being logged in is not enough: asking for proof again before sensitive actions

Three questions instead of one

Which actions to protect

Asking for the right proof

Don't break the flow

The re-authentication screen is a login screen

Before Symfony 8.2: a timestamp in the session

What Symfony 8.2 brings

Try it

PHP2Shell: how I patched my Symfony server

1. Know which PHP actually runs

2. A stopgap while waiting for the fix

3. Rebuild the image with the fixed PHP

4. A safety net for next time

5. What I take away

Sources

Event bursts: debounce, uniqueness or rate limiting, which should you use?

The starting bug: unique, but stale

The fix: wait for the burst to end

How it works

Jobs are created, then thrown away

The cache becomes a coordination point

The last event gets processed, with the delay on top

The continuous-stream trap: maxWait

Process the state, not the event

Debounce, uniqueness, rate limiting: the table

When per-object debouncing is no longer enough

Testing a debounce

The continuous-stream trap: `maxWait`

`ignored_groups` is not `#[Ignore]`