The version field protects the row, not the client, and that gap is a 412

The interesting part of the design is the refusal to collapse the two checks into one. A conditional request handler that validates If-Match and then hands off to the controller has done something useful, but the author's own sequence spells out the hole: the header is checked, the version matches, another request writes the row, and only then does the controller call flush() [s1c8]. Everything between step one and step four is unguarded. So the bundle keeps the Doctrine version check as the thing that actually protects the write, and translates a Doctrine optimistic lock exception at flush time into 412 Precondition Failed [s1c9] so the client sees the same failure regardless of which of the two gates caught it.

That is the sane split. The database enforces atomicity on the row; HTTP enforces that the representation the client edited is still current when the request lands [s1c10]. Neither substitutes for the other, and a client that only ever hears about the second one gets an error code it can retry against rather than a silent overwrite [s1c1].

The status code taxonomy is where operators should look, because it is the part that reaches clients. A stale If-Match gets 412 [s1c6]. No If-Match at all gets 428 Precondition Required [s1c7], which is a policy decision, not a protocol requirement: the endpoint has decided that unconditional writes are not allowed rather than letting them through. Malformed conditional headers get 400 [s1c11]. Three distinct failure modes, three distinct codes, and any client library that treats them as one "it didn't work" bucket will retry the wrong one.

The honest caveat in the post is the one most implementations of this pattern skip. An ETag validates a representation, not a database row [s1c12]. Entity identity plus version is adequate only when nothing else moves the response, and the author lists what does move it: locale, serializer groups, related entities, user-specific fields, query parameters [s1c13]. If any of those change without bumping the entity version, the ETag is lying about what the client holds. The bundle's answer is an explicit scope string on both the read and write attributes, plus a pluggable EntityTagProviderInterface [s1c14], and the read example carries scope 'document-detail-v1' [s1c3] rather than defaulting to something implicit. Version the representation, not just the entity.

One small operational note: the default validator derives the tag from entity identity, Doctrine version and scope, but does not put the raw ID and version into the header [s1c5]. That keeps a monotonically increasing integer off the wire, which matters less for correctness than for what an ETag would otherwise leak about write volume on a resource.

The whole thing is roughly two attributes of surface area, #[EntityTag] on the read and #[RequireIfMatch] on the write [s1c3][s1c4], sitting on top of a Doctrine entity that already has #[ORM\Version] [s1c2]. That is cheap enough that the argument against it is not effort. It is that adding 428 to a write endpoint breaks every existing client that does not send If-Match, which is a versioning problem, not a concurrency one.