Request / Response Macros

When this package's service provider is registered, it installs a few Http Request & Response Macros. These provide, among other, some shortcut methods to obtain etags from conditional headers or to set cache headers with an etag.

• Request Macros
  • ifMatchEtags()
  • ifNoneMatchEtags()
  • ifModifiedSinceDate()
  • ifUnmodifiedSinceDate()
  • ifRangeEtagOrDate()
• Response Macros
  • withEtag()
  • withoutEtag()
  • withCache()

Request Macros

ifMatchEtags()

The ifMatchEtags() returns a collection or ETag instances, from the If-Match Http header.

$collection = $request->ifMatchEtags();

if ($collection->isNotEmpty()) {
    // ...remaining not shown ...
}

ifNoneMatchEtags()

Returns a collection or ETag instances, from the If-None-Match Http header.

$collection = $request->ifNoneMatchEtags();

if ($collection->isEmpty()) {
    // ...remaining not shown ...
}

ifModifiedSinceDate()

Returns a DateTime instance of the If-Modified-Since Http header, or null if not set.

$datetime = $request->ifModifiedSinceDate();

if (!is_null($datetime)) {
    // ...remaining not shown ...
}

Note: The method will return null if the HTTP Method is not GET or HEAD, or if the request contains an If-None-Match header. See RFC-9110 for additional information.

ifUnmodifiedSinceDate()

Returns a DateTime instance of the If-Unmodified-Since Http header, or null if not set.

$datetime = $request->ifUnmodifiedSinceDate();

if ($datetime instanceof \DateTimeInterface) {
    // ...remaining not shown ...
}

Note: The method will return null if the request contains an If-Match header. See RFC-9110 for additional information.

ifRangeEtagOrDate()

The If-Range Http header is slightly special. It can contain an HTTP-Date or an ETag value. Therefore, the ifRangeEtagOrDate() method will return one of the following:

• DateTime instance
• ETag instance
• null (if the If-Range header was not set, or if request does not contain a Range header. See RFC-9110 for additional information).

use Aedart\Contracts\ETags\ETag;

$value = $request->ifRangeEtagOrDate();

if ($value instanceof ETag) {
    // ... not shown ...
} elseif ($value instanceof \DateTimeInterface) {
    // ... not shown ...
} else {
    // "If-Range" was not requested, or "Range" header was not set...
}

Response Macros

withEtag()

The withEtag() method allows you to set the ETag Http header, from an ETag instance. Note: This method is an adaptation of Symfony's setEtag().

use Aedart\ETags\Facades\Generator;
use Illuminate\Http\Response;

$etag = Generator::makeStrong('my-content');

$response = (new Response())
    ->withEtag($etag);

withoutEtag()

If you need to remove a response's ETag Http header, use the withoutEtag().

$response = (new Response())
    ->withEtag($etag);

// Later in your application - remove ETag
$response->withoutEtag();

withCache()

The withCache() method is an adapted version of Symfony's setCache(), that allows an ETag instance to be specified, along with the rest of the cache headers.

$etag = Generator::makeStrong('my-content');

$response = (new Response())
    ->withCache(
        etag: $etag,
        lastModified: now()->addHours(3)->addSeconds(43),
        private: true
    );