doc: more documentation

.github/workflows/coverals-and-codecov.yml

@@ -9,6 +9,7 @@ on:
       - 'LICENSE'
       - 'CHANGELOG.md'
       - 'CONTRIBUTING.md'
+      - 'doc/**'
 
 jobs:
   phpunit:

.github/workflows/phpunit.yml

@@ -7,6 +7,7 @@ on:
       - 'LICENSE'
       - 'CHANGELOG.md'
       - 'CONTRIBUTING.md'
+      - 'doc/**'
 
 jobs:
   phpunit:

README.md

@@ -1,12 +1,13 @@
-# HTTP Cache - `smartondev/httpcache`
+# Build HTTP cache headers, ETag and modified matchers
 
 ![GitHub Release](https://img.shields.io/github/v/release/smartondev/httpcache?include_prereleases)
 [![GitHub License](https://img.shields.io/github/license/smartondev/httpcache)](LICENSE)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/smartondev/httpcache/phpunit.yml?label=tests)
-[![Coverage Status](https://img.shields.io/coverallsCoverage/github/smartondev/httpcache)](https://coveralls.io/github/smartondev/httpcache?branch=main)
-[![Codecov](https://img.shields.io/codecov/c/github/smartondev/httpcache)](https://app.codecov.io/gh/smartondev/httpcache)
+[![Coverage Status](https://img.shields.io/coverallsCoverage/github/smartondev/httpcache?label=coveralls)](https://coveralls.io/github/smartondev/httpcache?branch=main)
+[![Codecov](https://img.shields.io/codecov/c/github/smartondev/httpcache?label=codecov)](https://app.codecov.io/gh/smartondev/httpcache)
 
-**This code is under development and not ready for production use.**
+This package helps you to build HTTP cache headers like `Cache-Control`, `ETag` and matchers like `If-None-Match`,
+`If-Modified-Since`. It is useful for building HTTP cache headers and matchers in your application.
 
 ## Installation
 
@@ -95,6 +96,13 @@ $builderB = $builderA->withMaxAge(60);
 $builderC = $builderB->withoutMaxAge();
 ```
 
+### More documentation
+
+- [CacheHeaderBuilder](doc/cache-header-builder.md): building cache headers like `Cache-Control`
+- [ETagHeaderBuilder](doc/etag-header-builder.md): building ETag header
+- [ETagMatcher](doc/etag-matcher.md): matching ETag headers like `If-Match`, `If-None-Match`
+- [ModifiedMatcher](doc/modified-matcher.md): matching modified headers like `If-Modified-Since`, `If-Unmodified-Since`
+
 ## Contributing
 
 Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

doc/cache-header-builder.md

@@ -0,0 +1,51 @@
+# `CacheHeaderBuilder` class
+
+The `CacheHeaderBuilder` class is used to build cache headers like `Cache-Control`, `ETag`.
+
+## Usage
+
+### No-cache
+
+Strongly no caching. No caching in browser, no caching in proxy.
+
+Recommended for sensitive data or data that changes frequently.
+
+```php
+$noCacheHeaders = (new CacheHeaderBuilder())
+    ->noCache()
+    ->toHeaders();
+```
+
+### Caching in browser in private mode
+
+Caching in browser for 1 hour. No caching in proxy.
+
+```php
+$headers = (new CacheHeaderBuilder())
+    ->maxAge(hours: 1)
+    ->private()
+    ->toHeaders();
+```
+
+### Caching public
+
+Caching in browser (and in proxy) for 1 hour.
+
+```php
+$headers = (new CacheHeaderBuilder())
+    ->maxAge(hours: 1)
+    ->public()
+    ->toHeaders();
+```
+
+### Caching in CDN
+
+Caching in CDN for 60 seconds, shared max age 30 seconds.
+
+```php
+$headers = (new CacheHeaderBuilder())
+    ->maxAge(30)
+    ->public()
+    ->sharedMaxAge(60)
+    ->toHeaders();
+```

doc/etag-header-builder.md

@@ -0,0 +1,39 @@
+# `ETagHeaderBuilder` class
+
+The `ETagHeaderBuilder` class is used to build the `ETag` header.
+
+The `ETag` header is a string that uniquely identifies a specific version of a resource. It is used to determine if the
+resource has changed since the last request.
+
+## Usage
+
+### Week ETag
+
+Generate a week ETag. The ETag will be a hash of the content and not represent the real version of the resource.
+
+```php
+$headers = (new ETagHeaderBuilder())
+    ->withEtag('123456')
+    ->withWeekEtag()
+    ->toHeaders();
+```
+
+### ETag
+
+Generate a strong ETag. The ETag will be a hash of the content and represent the real version of the resource.
+
+```php
+$headers = (new ETagHeaderBuilder())
+    ->etag('123456')
+    ->toHeaders();
+```
+
+### ETag from content
+
+Generate a strong ETag from the content with a specific hash algorithm.
+
+```php
+$headers = (new ETagHeaderBuilder())
+    ->computedETag($content, 'md5')
+    ->toHeaders();
+```

doc/etag-matcher.md

@@ -0,0 +1,14 @@
+# `ETagMatcher` class
+
+The `ETagMatcher` class is used to match the `ETag` header of the request like `If-Match`, `If-None-Match`.
+
+## Usage
+
+### If-Match
+
+...
+
+### If-None-Match
+
+...
+

doc/modified-matcher.md

@@ -0,0 +1,22 @@
+# `ModifiedMatcher` class
+
+The `ModifiedMatcher` class is used to check if the request headers contain the `If-Modified-Since` header and if the
+last modified date is greater than the date in the header.
+
+Additionally, it can check if the request headers contain the `If-Unmodified-Since` header and if the last modified date
+is less than or equal to the date in the header.
+
+## Usage
+
+### If-Modified-Since
+
+Check if the resource has been modified since the date specified in the `If-Modified-Since` header.
+
+...
+
+### If-Unmodified-Since
+
+Check if the resource has not been modified since the date specified in the `If-Unmodified-Since` header.
+
+...
+