Download the PHP package expertsystemsau/laravel-conditional-requests without Composer

Conditional requests are the part of HTTP that lets a client and a server agree on which version of a resource they are talking about, before either of them acts on it. RFC 9110 §13 defines them; ETag and Last-Modified are just the two validators underneath.

They solve two different problems with the same handshake:

• Reads — the client already holds version v7. If nothing has changed, it should get an empty 304 Not Modified instead of the payload again. Less bandwidth, less serialization, faster clients.
• Writes — the client read version v7, edited it, and is now sending it back. If someone else saved v8 in between, the write must be refused, not silently applied over the top. This is the lost update problem, and If-Match is the fix.

Most Laravel packages in this space only do the first half, and only via ETag. This one treats conditional requests as the feature and validators as an implementation detail.

Requirements

• PHP 8.3, 8.4, or 8.5
• Laravel 12.x or 13.x

Installation

Install the package via Composer:

The service provider is auto-discovered. No further setup is required to get started.

Quickstart

A conditional read. Apply the middleware to a route that returns a cacheable representation. The response gets a validator, and a matching subsequent request is answered 304 Not Modified with an empty body.

A guarded write. Add required to a route that changes something, and the client has to say which version it believes it is modifying. Add the contract and the trait to the model so the middleware can ask the record its version:

That is the whole surface. docs/writes.md cover everything else.

Before you put this in front of users

Six things can bite you. Each is one click away, and the full register has twelve more with a scan table.

• A client that holds a valid tag keeps getting 304 after you revoke its access — anything declared after conditional does not run on a hit. → H1
• A version column that does not change on every write freezes the tag and serves 304 against content that changed. → H3
• Under model the tag is scoped to the record, not to the viewer, the tenant row, or the Accept header — one client's tag gets honoured for another. → H5
• A short-circuited 304 carries the framework's Cache-Control, and a cache adopts it: your public, max-age=60 becomes private, no-cache permanently. → H6
• Any middleware that changes the response body outside conditional makes the tag describe bytes nobody received — a frozen CSP nonce, a stale CSRF token. → H7
• lock runs your controller inside a transaction: jobs dispatch before the commit, and returning an error response commits rather than rolls back. → H9

Header reference

Documentation

• Conditional reads — strategies, the pre-controller short-circuit, Last-Modified, custom strategies
• Conditional writes — If-Match, 412, 428, the create guard, lock
• Placement and ordering — where conditional goes, and what changes if it goes elsewhere
• Configuration — every key and what it governs
• Hazards — the register, with a scan table
• Public API and stability — what semver covers

Coming from werk365/etagconditionals?

The migration guide maps setEtag, ifNoneMatch, ifMatch and the etag group onto conditional and its flags, lists the behaviour changes you will hit on day one, and says plainly when not to bother.

Stability

v1.0.0 and later follow Semantic Versioning. docs/api.md names exactly what that covers — every contract, the trait, the middleware alias and its flags, the config keys, the exceptions. Anything not on that list is internal and may change in any release.

The list is not a promise in prose: tests/Feature/PublicApiTest.php reflects the actual surface and fails when it differs from the frozen one.

Testing

composer test:lock is not part of composer test, so the suite stays runnable with nothing but PHP and SQLite. It proves that a competing session's row lock forces a 503, which SQLite cannot demonstrate at all — lockForUpdate() compiles to nothing there. Point it at a database you can throw away:

Without those variables every test in it skips, naming them. CI runs it against MySQL and PostgreSQL on every push and fails if it skipped.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Conditional Requests! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mitchell Williams
• All Contributors

Prior art: werk365/etagconditionals mapped out this territory for Laravel first, and is worth a look if you need something available today.

License

Laravel Conditional Requests is open-sourced software licensed under the MIT license.