aedart / athenaeum-etags
ETags utilities and Http Conditional Request evaluation for your Laravel Application
Requires
- php: ^8.2
- aedart/athenaeum-contracts: ^8.13
- aedart/athenaeum-streams: ^8.13
- aedart/athenaeum-support: ^8.13
- aedart/athenaeum-utils: ^8.13
- illuminate/http: ^v11.29.0
- ramsey/http-range: ^1.1.0
- dev-main
- 8.13.0
- 8.12.0
- 8.11.0
- 8.10.0
- 8.9.0
- 8.8.0
- 8.7.0
- 8.6.0
- 8.5.0
- 8.4.0
- 8.3.0
- 8.2.0
- 8.1.0
- 8.0.0
- 7.33.0
- 7.32.0
- 7.31.0
- 7.30.1
- 7.30.0
- 7.29.0
- 7.28.0
- 7.27.0
- 7.26.0
- 7.25.0
- 7.24.0
- 7.23.0
- 7.22.1
- 7.22.0
- 7.21.0
- 7.20.0
- 7.19.0
- 7.18.1
- 7.18.0
- 7.17.0
- 7.16.0
- 7.15.0
- 7.14.0
- 7.13.0
- 7.12.0
- 7.11.3
- 7.11.2
- 7.11.1
- 7.11.0
- 7.10.1
- 7.10.0
- 7.9.1
- 7.9.0
- 7.8.0
- 7.7.2
- 7.7.1
- 7.7.0
- 7.6.0
- 7.5.0
- 7.4.0
- 7.3.0
- 7.2.0
- 7.1.0
- 7.0.1
- 7.0.0
- 7.0.0-alpha.1
- 6.8.1
- 6.8.0
- 6.7.0
- 6.6.0
This package is auto-updated.
Last update: 2024-10-29 12:59:25 UTC
README
This package provides a "profile" based approach to generate ETags, and an evaluator to deal with Http Conditional Requests, for your Laravel application.
ETags Examples
Generate
use Aedart\ETags\Facades\Generator; // Generate an ETag for strong comparison, of content $etag = Generator::makeStrong($content); echo (string) $etag; // "4720b076892bb2fb65e75af902273c73a2967e4a"
Or to generate ETags that are flagged as "weak" (for weak comparison)
$etag = Generator::makeWeak($content); echo (string) $etag; // W/"0815"
Parsing
To parse ETags from Http headers, you can use the parse()
method. It returns a collection of ETag
instances.
// E.g. If-None-Match: W/"0815", W/"0816", W/"0817" $collection = Generator::parse($request->header('If-None-Match')); foreach ($collection as $etag) { echo (string) $etag; }
Compare
ETags can also be matched against each other, in accordance with RFC9110.
Using Collection
// Etags from Http Header $collection = Generator::parse($request->header('If-Match')); // E.g. 'W/"0815"' // Other Etag for your resource $etag = Generator::makeWeak($content); // E.g. W/"0815" // Compare etags against resource's etag echo $collection->contains($etag, true); // false - strong comparison echo $collection->contains($etag); // true - weak comparison
Using Etag instance
You can also compare individual ETag
instances, using the matches()
method.
$etagA = Generator::parseSingle('W/"0815"'); $etagB = Generator::parseSingle('W/"0815"'); echo $etagA->matches($etagB, true); // false - strong comparison echo $etagA->matches($etagB); // true - weak comparison
Evaluate Http Preconditions Examples
The Evaluator
component is able to process the incoming request against all the defined RFC9110 preconditions, in accordance with specified evaluation precedence.
Depending on the precondition requested, if it passes or fails, the request can either proceed or it will be aborted using customisable Http Exceptions.
Your Laravel application should do the rest, whenever the request is aborted.
use Aedart\ETags\Preconditions\Evaluator; use Aedart\ETags\Preconditions\Resources\GenericResource; // Process If-Match, If-None-Match, If-Modified-Since... etc // Depending on condition's pass/fail, the request can be aborted via // an appropriate Http Exception, or proceed to your logic... $resource = Evaluator::make($request) ->evaluate(new GenericResource( data: $model, etag: $model->getStrongEtag(), lastModifiedDate: $model->updated_at ));
To summarise, the following preconditions are supported:
The Evaluator
also supports adding your own custom preconditions to be evaluated, should you need such.
Official Documentation
Please read the official documentation for additional information.
The mono repository is located at github.com/aedart/athenaeum
Versioning
This package follows Semantic Versioning 2.0.0
License
BSD-3-Clause, Read the LICENSE file included in this package