aedart/athenaeum-etags

为您的Laravel应用程序提供ETags工具和Http条件请求评估

8.10.0 2024-09-23 07:54 UTC

README

此包提供了一种基于"配置文件"的方法来生成ETags,并为处理Http条件请求提供了一个评估器,适用于您的Laravel应用程序。

ETags示例

生成

use Aedart\ETags\Facades\Generator;

// Generate an ETag for strong comparison, of content
$etag = Generator::makeStrong($content);

echo (string) $etag; // "4720b076892bb2fb65e75af902273c73a2967e4a"

或者生成标记为"弱"的ETags(用于弱比较

$etag = Generator::makeWeak($content);

echo (string) $etag; // W/"0815"

解析

要解析Http头中的ETags,您可以使用parse()方法。它返回一个包含ETag实例的集合。

// 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;
}

比较

ETags也可以根据RFC9110进行相互匹配。

使用集合

// 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

使用ETag实例

您还可以使用matches()方法比较单个ETag实例。

$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

Http预处理条件示例

Evaluator组件能够处理传入请求与所有定义的RFC9110预处理条件,按照指定的评估优先级。根据请求的预处理条件,如果通过或失败,请求可以继续进行或通过可定制的Http异常中止。您的Laravel应用程序应在请求中止时完成剩余操作。

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
    ));

总结如下,以下预处理条件受支持

Evaluator还支持添加您自己的自定义预处理条件进行评估,如果您需要的话。

官方文档

请阅读官方文档以获取更多信息。

单一代码库位于github.com/aedart/athenaeum

版本控制

此包遵循语义版本控制2.0.0

许可证

BSD-3-Clause,请阅读包含在此包中的LICENSE文件