You are viewing documentation for an outdated version. It is no longer supported!

Request / Response Macros

Etags and precondition evaluator components depend on a few Http Request & Response Macrosopen in new window. These are automatically installed by this package's service provider. The following highlights the macros that are installed.

Request Macros

ifMatchEtags()

The ifMatchEtags() returns a collection or ETag instances, from the If-Match Http headeropen in new window.

$collection = $request->ifMatchEtags();

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

ifNoneMatchEtags()

Returns a collection or ETag instances, from the If-None-Match Http headeropen in new window.

$collection = $request->ifNoneMatchEtags();

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

ifModifiedSinceDate()

Returns a DateTimeopen in new window instance of the If-Modified-Since Http headeropen in new window, 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-9110open in new window for additional information.

ifUnmodifiedSinceDate()

Returns a DateTimeopen in new window instance of the If-Unmodified-Since Http headeropen in new window, 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-9110open in new window for additional information.

ifRangeEtagOrDate()

The If-Range Http headeropen in new window is slightly special. It can contain an HTTP-Dateopen in new window or an ETag valueopen in new window. Therefore, the ifRangeEtagOrDate() method will return one of the following:

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 headeropen in new window, from an ETag instance. Note: This method is an adaptation of Symfony's setEtag()open in new window.

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()open in new window, 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
    );