PHPackages                             bakame/http-cache-status - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. bakame/http-cache-status

ActiveLibrary[HTTP & Networking](/categories/http)

bakame/http-cache-status
========================

Cache-Status HTTP Response Header Field in PHP

1.0.0(4mo ago)00MITPHPPHP ^8.2CI passing

Since Feb 12Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/bakame-php/http-cache-status)[ Packagist](https://packagist.org/packages/bakame/http-cache-status)[ Docs](https://github.com/bakame-php/http-cache-status)[ GitHub Sponsors](https://github.com/sponsors/nyamsprod)[ RSS](/packages/bakame-http-cache-status/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (9)Versions (2)Used By (0)

Cache-Status HTTP Header Field
------------------------------

[](#cache-status-http-header-field)

This package contains classes used to parse, validate and manipulate the [Cache-Status HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9211.html).

System Requirements
-------------------

[](#system-requirements)

**PHP >= 8.2** is required but the latest stable version of PHP is recommended.

Usage
-----

[](#usage)

Unless explicitly stated, all the classes described hereafter are immutable.

### Parsing

[](#parsing)

The package can parse the Header from ab HTTP Request or Response using the `Field` class as follows:

```
use Bakame\Http\CacheStatus\Field;
use Bakame\Http\CacheStatus\ForwardedReason;
use Bakame\Http\CacheStatus\HandledRequestCache;

/* @var Psr\Http\Message\ResponseInterface $response */
$headerLine = $response->getHeaderLine(Field::NAME);
// 'ReverseProxyCache; hit, ForwardProxyCache; fwd=uri-miss; collapsed; stored';
$statusCode = $response->getStatusCode(); //304

$cacheStatus = Field::fromHttpValue($headerLine, $statusCode);
```

### Field Container

[](#field-container)

The `Field` class is a container whose members are handled request cache information as they are added by the various servers. The class implements PHP's `IteratorAggregate`, `ArrayAccess`, `Countable` and `Stringable` interface.

```
echo $cacheStatus;    // returns 'ReverseProxyCache; hit, ForwardProxyCache; fwd=uri-miss; collapsed; stored';
$cacheStatus[1];      // returns a HandledRequestCache instance
count($cacheStatus);  // returns 2
```

You can also determine if a specific handled cache request exist either by supplying the cache index or its server identifier

```
$cacheStatus->contains(Token::fromString('foobar')); // returns false
$cacheStatus->indexOf(Token::fromString('foobar')); // returns null
$cacheStatus->contains(Token::fromString('ReverseProxyCache')); // returns true
$cacheStatus->indexOf(Token::fromString('ReverseProxyCache'));  // returns 0
```

As per the RFC the `closestToOrigin` and `closestToUser` methods give you access to the caches closest to the origin server and the one closest to the client (user).

```
$cacheClosestToTheOrigin = $cacheStatus->closestToOrigin(); // the handled request cache closest to the origin server
$cacheClosestToTheClient = $cacheStatus->closestToUser(); // the handled request cache closest to the user
```

Both methods return `null` if no `HandledRequestCache` instance is found.

### The Handled Request Cache object

[](#the-handled-request-cache-object)

```
$cacheClosestToTheOrigin->hit; // return true
$cacheClosestToTheOrigin->forward; // return null
$cacheClosestToTheClient->hit; // return false
$cacheClosestToTheClient->forward->reason; // return ForwardReason::UriMiss
$cacheClosestToTheClient->forward->statusCode; // return 304
```

A `HandledRequestCache` instance contains information about the cache and how it was handled for the current message. In particular, in compliance with the RFC, if the `forward` property is present you will get extra information regarding the reason why the cache was forwarded. From the POV of the cache the only required check needed is the following:

```
if ($cacheClosestToTheOrigin->hit) {
    //this is a hit, the 'forward' property is null
    $cacheClosestToTheOrigin->forward; // returns null
} else {
    //not a hit, the 'forward' property is a Forward instance
    $cacheClosestToTheOrigin->forward; // return Forward class
    $cacheClosestToTheClient->forward->reason; // return ForwardReason::UriMiss
    $cacheClosestToTheClient->forward->statusCode; // return 304
    if ($cacheClosestToTheClient->forwardReason->isOneOf(ForwardedReason::Miss, ForwardedReason::UriMiss)) {
        //you can do something useful here
    }
}
```

The class lists all the available reason via the `ForwardedReason` Enum.

You can push more `HandledRequestCache` instances to the `Field` container using the `push` method. The method supports pushing `HandledRequestCache` instances as well as HTTP text representation of the handled request cache.

```
$newCacheStatus = $cacheStatus->push(
    HandledRequestCache::serverIdentifierAsToken('BrowserCache')
        ->wasForwarded(Forward::fromReason(ForwardedReason::UriMiss))
);
// or you can use push an HTTP header
$newCacheStatus = $cacheStatus->push('BrowserCache; fwd=uri-miss');
```

### Serializing the message field

[](#serializing-the-message-field)

Once you have created or updated you `Field` instance you just need to add it to your response header using the `toHttpValue` method or the `__toString()` to generate the correct HTTP text representation to insert in your message header.

```
// or you can use push an HTTP header
$newCacheStatus = $cacheStatus->push('BrowserCache; fwd=uri-miss');

$newResponse = $response->withHeader(Field::NAME, $newCacheStatus);
echo $response->getHeaderLine(Field::NAME);
```

**While we used PSR-7 ResponseInterface, The package parsing and serializing methods can use any HTTP abstraction package or PHP `$_SERVER` array.**

```
$cacheStatus = Field::fromSapiServer($_SERVER, Field::SAPI_NAME);
$newCacheStatus = $cacheStatus->push('BrowserCache; fwd=uri-miss');

header(Field::NAME.': '.$newCacheStatus);
```

In this last example we use PHP native function to parse and add the correct header to the PHP emitted HTTP response.

Structured Fields
-----------------

[](#structured-fields)

Because the Header field is compliant with the HTTP Structured Field RFC. We can easily parse it **but** were are also validating it against its specific RFC rules. To do so the package is dependent on the [HTTP Structured Fields for PHP](https://github.com/bakame-php/http-structured-fields) v2.0 package, which remove all the boilerplate needed for such header to be parsed, validated and manipulated in PHP while staying compliant with all the different RFCs.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance74

Regular maintenance activity

Popularity0

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 97.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

141d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/51073?v=4)[Ignace Nyamagana Butera](/maintainers/nyamsprod)[@nyamsprod](https://github.com/nyamsprod)

---

Top Contributors

[![nyamsprod](https://avatars.githubusercontent.com/u/51073?v=4)](https://github.com/nyamsprod "nyamsprod (47 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

httpheaderstructured-fieldcache-statusrfc9211response-header

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bakame-http-cache-status/health.svg)

```
[![Health](https://phpackages.com/badges/bakame-http-cache-status/health.svg)](https://phpackages.com/packages/bakame-http-cache-status)
```

###  Alternatives

[ptlis/conneg

Tools for performing content negotiation.

365.4k1](/packages/ptlis-conneg)[chelout/laravel-http-logger

A Laravel package to log HTTP requests, headers and sessions

262.0k](/packages/chelout-laravel-http-logger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)