DEV Community: Arnaud POINTET

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.