### Install Documentation Requirements

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/contributing.rst

Install the necessary Python packages for building the documentation using pip.

```bash
$ pip install -r Resources/doc/requirements.txt
```

--------------------------------

### Install FOSHttpCacheBundle with Symfony HttpClient

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/overview.rst

Use this command to install the FOSHttpCacheBundle along with Symfony HttpClient and necessary PSR-7 implementations. Ensure you have a PSR-7 implementation and an HTTP client implementation available in your project.

```bash
$ composer require friendsofsymfony/http-cache-bundle symfony/http-client nyholm/psr7 guzzlehttp/promises
```

--------------------------------

### Basic Match Configuration

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Example of a basic match configuration using host, path, and query string regular expressions.

```yaml
match:
    host: ^login.example.com$
    path: ^/
    query_string: (^|&)token=
```

--------------------------------

### Clone and Test FOSHttpCacheBundle

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/testing.rst

Clone the FOSHttpCacheBundle repository, install its dependencies using Composer, and then run the tests with PHPUnit.

```bash
$ git clone https://github.com/FriendsOfSymfony/FOSHttpCacheBundle.git
$ cd FOSHttpCacheBundle
$ composer install
$ vendor/bin/simple-phpunit
```

--------------------------------

### Install Symfony ExpressionLanguage Component

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/overview.rst

Install the Symfony ExpressionLanguage component if you intend to use expressions in your bundle attributes. This is an optional dependency.

```bash
$ composer require symfony/expression-language
```

--------------------------------

### Adjust Front Controller for HttpCache

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/symfony-http-cache.rst

Modify your front controller (e.g., public/index.php) to use the HttpCache instance obtained from the kernel, ensuring consistent setup across all entry points.

```php
use App\AppKernel;

// ...

$kernel = new AppKernel($env, $debug);
if ('prod' === $env) {
    $kernel = $kernel->getHttpCache();
}

// ...
```

--------------------------------

### Manually Control Caching Proxy in Tests

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/testing.rst

Manually control the caching proxy within your test methods by using getProxy() to start, clear, and stop the proxy. This provides fine-grained control over the test environment.

```php
use FOS\HttpCache\Test\ProxyTestCase;

class YourTest extends ProxyTestCase
{
    public function testMiss()
    {
        // Start caching proxy
        $this->getProxy()->start();

        // Clear proxy cache
        $this->getProxy()->clear();

        $this->assertMiss($this->getResponse('/your/page'));

        // Stop caching proxy
        $this->getProxy()->stop();
    }
}
```

--------------------------------

### Define Basic Tagging Rule

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/tags.rst

Define a tagging rule that matches requests to paths starting with '/news' and applies the 'news-section' tag.

```yaml
# app/config/config.yml
fos_http_cache:
    tags:
        rules:
            - 
                match:
                    path: ^/news
                tags: [news-section]
```

--------------------------------

### Define Tagging Rule with Dynamic Expressions

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/tags.rst

Define a tagging rule that matches requests to paths starting with '/articles' and dynamically generates tags using an expression. The expression 'article-'~id will create tags like 'article-123' for requests to '/articles/123'.

```yaml
# app/config/config.yml
fos_http_cache:
    tags:
        rules:
            - 
                match:
                    path: ^/articles
                tags: [articles]
                tag_expressions: ["'article-'~id"]
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/contributing.rst

Navigate to the doc directory and use make to build the HTML documentation.

```bash
$ cd doc
$ make html
```

--------------------------------

### Configure Fastly Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Use this configuration to set up the Fastly proxy client. Ensure you provide your service identifier and authentication token. Soft purges are enabled by default.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        fastly:
            service_identifier: '<my-service-identifier>'
            authentication_token: '<my-authentication-token>'
            soft_purge: true
```

--------------------------------

### Cache Invalidation Configuration

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/invalidation.rst

Define invalidation rules in app/config/config.yml to automatically purge specific routes when other routes are modified. This example purges 'villains_index' and 'villain_details' when 'villain_edit' or 'villain_delete' are matched.

```yaml
# app/config/config.yml
fos_http_cache:
    invalidation:
        rules:
            - 
                match:
                    attributes:
                        _route: "villain_edit|villain_delete"
                routes:
                    villains_index: ~    # e.g., /villains
                    villain_details: ~   # e.g., /villain/{id}
```

--------------------------------

### Configure Proxy Server for Testing

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/testing.rst

Configure the proxy server settings in app/config/config_test.yml for testing purposes. This includes specifying the Varnish binary, port, and configuration file.

```yaml
// app/config/config_test.yml
fos_http_cache:
    test:
        proxy_server:
            varnish:
                binary: /usr/sbin/varnishd
                port: 8080
                config_file: /etc/varnish/your-config.vcl
```

--------------------------------

### Configure Test Proxy Server and Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/test.rst

Use this configuration in `config_test.yml` to set up proxy server details and enable/disable specific proxy clients for testing.

```yaml
// app/config/config_test.yml
fos_http_cache:
    test:
        proxy_server:
            varnish:
                config_file: /etc/varnish/your-config.vcl
                port: 8080
                binary: /usr/sbin/varnish
        client:
            varnish:
                enabled: true
            nginx:
                enabled: false
```

--------------------------------

### Use @clearCache Annotation for Test Isolation

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/testing.rst

Use the @clearCache PHPUnit annotation on test methods or classes to ensure isolated test cases by automatically starting and clearing the caching proxy before each test.

```php
use FOS\HttpCache\Test\ProxyTestCase;

class YourTest extends ProxyTestCase
{
    /**
     * @clearCache
     */
    public function testMiss()
    {
        // We can be sure this is a miss, because even if the content was
        // cached before, it has been cleared from the caching proxy.
        $this->assertMiss($this->getResponse('/your/page'));
    }
}
```

--------------------------------

### Tag Custom User Context Provider Service (PHP)

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Register a custom service as a user context provider using PHP configuration. The 'priority' option in the tag determines execution order.

```php
$container
    ->register('acme.demo_bundle.my_service', '%acme.demo_bundle.my_service.class%')
    ->addTag('fos_http_cache.user_context_provider', array('priority' => 10))
;
```

--------------------------------

### Tag Responses with a Specific Tag

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/attributes.rst

Apply the Tag attribute to a controller action to automatically tag the response. Safe requests (GET, HEAD) will tag the response, while modifying requests will invalidate tags.

```php
use FOS\HttpCacheBundle\Configuration\Tag;

#[Tag('news-article')]
public function showAction()
{
    // ...
}
```

--------------------------------

### Tag Custom User Context Provider Service (XML)

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Register a custom service as a user context provider using XML configuration. The 'priority' attribute determines execution order.

```xml
<service id="acme.demo_bundle.my_service" class="%acme.demo_bundle.my_service.class%">
    <tag name="fos_http_cache.user_context_provider" priority="10" />
</service>
```

--------------------------------

### Configure Varnish IPs and Ports

Source: https://github.com/friendsofsymfony/foshttpcachebundle/wiki/Migrating-from-LiipCacheControlBundle

The Varnish port configuration is now merged into the 'ips' parameter, accepting a list of host:port combinations.

```yaml
fos_http_cache
    varnish:
        ips: ['10.0.10:8080', '10.0.10:8080']
```

--------------------------------

### Configure CloudFront Proxy Client with Custom Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the CloudFront proxy client using a custom client service. Requires the 'jean-beru/fos-http-cache-cloudfront' library.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        cloudfront:
            distribution_id: '<my-distribution-id>'
            client: '<my.custom.client>'
```

--------------------------------

### Configure Invalidation Rules

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/invalidation.rst

Define rules to invalidate specific routes when other routes are requested. This example shows how to invalidate the 'villains_index' and 'villain_details' routes when 'villain_edit' or 'villain_delete' routes are accessed. The 'ignore_extra_params' option is set to false for 'villain_details', meaning extra parameters from the request will be used to construct the invalidated route.

```yaml
# app/config/config.yml
fos_http_cache:
    invalidation:
        enabled: true    # Defaults to 'auto'
        rules:
            - 
                match:
                    attributes:
                        _route: "villain_edit|villain_delete"
                routes:
                    villains_index: ~    # e.g., /villains
                    villain_details:     # e.g., /villain/{id}
                        ignore_extra_params: false    # Defaults to true
```

--------------------------------

### Tag Custom User Context Provider Service (YAML)

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Register a custom service as a user context provider using YAML configuration. The 'priority' tag determines execution order.

```yaml
acme.demo_bundle.my_service:
    class: "%acme.demo_bundle.my_service.class%"
    tags:
        - { name: fos_http_cache.user_context_provider, priority: 10 }
```

--------------------------------

### Configure Varnish Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the Varnish proxy client with custom headers, ban mode, and server details. Ensure all proxy servers are listed for consistent cache invalidation.

```yaml
fos_http_cache:
    proxy_client:
        varnish:
            tags_header: My-Cache-Tags
            tag_mode: ban
            header_length: 1234
            default_ban_headers:
                Foo: Bar
            http:
                servers:
                    - 123.123.123.1:6060
                    - 123.123.123.2
                # alternatively, if you configure the varnish servers in an environment variable:
                # servers_from_jsonenv: '%env(json:VARNISH_SERVERS)%'
                base_url: yourwebsite.com
```

--------------------------------

### YAML Alias for Reusable Headers

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Demonstrates using YAML aliases to define a set of headers once and reuse it across multiple rules. This helps in avoiding redundant configuration. Aliased configurations can still be partially overwritten.

```yaml
rules:
    - 
        match:
            path: ^/products.*
        headers: &public
            cache_control:
                public: true
                max_age: 600
                s_maxage: 300
            reverse_proxy_ttl: 3600
    - 
        match:
            path: ^/brands.*
        headers:
            << : *public
            cache_control:
                max_age: 1800

```

--------------------------------

### Configure Noop Proxy Client for Testing

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

The noop proxy client is useful for testing as it supports all invalidation methods but performs no actual operations. It can be set as the default client.

```yaml
# config/packages/test/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        default: noop
        noop: ~
```

--------------------------------

### Enable Cache Tagging

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/tags.rst

Set this to true to enable cache tagging. It's recommended to enable this to be notified of missing dependencies and incompatible proxies.

```yaml
# app/config/config.yml
fos_http_cache:
    tags:
        enabled: true
```

--------------------------------

### Configure CloudFront Proxy Client with Access Keys

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the CloudFront proxy client using access key ID and secret for AWS authentication. Requires the 'jean-beru/fos-http-cache-cloudfront' library.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        cloudfront:
            distribution_id: '<my-distribution-id>'
            configuration:
                accessKeyId: '<my-access-key-id>'
                accessKeySecret: '<my-access-key-secret>'
```

--------------------------------

### Enable User Context Listener

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/user-context.rst

Enable the user context listener in the main configuration to activate the user context caching mechanism.

```yaml
fos_http_cache:
    user_context:
        enabled: true
```

--------------------------------

### Check Documentation Spelling

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/contributing.rst

Use the make spelling command to check for spelling errors in the documentation.

```bash
$ make spelling
```

--------------------------------

### Match Controller Name

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Use a regular expression to match the controller name. Ensure you use the full controller name, including the namespace.

```yaml
match:
    attributes: { _controller: ^AcmeBundle:Default:.* }
```

--------------------------------

### Enable Flash Message Listener Configuration

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/helpers/flash-message.rst

Enable the flash message listener by setting 'enabled' to true in your configuration.

```yaml
# app/config.yml
fos_http_cache:
    flash_message:
        enabled: true
```

--------------------------------

### Refresh a Path

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/cache-manager.rst

Use refreshPath() to immediately fetch a fresh copy of content for a given path from the backend. Ensure your proxy is configured for purging.

```php
$cacheManager->refreshPath('/users');
```

--------------------------------

### Define Route for User Context Hash

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/user-context.rst

Configure a route for handling user context hash requests. This route does not require a controller as the listener aborts the request after firewall application.

```yaml
user_context_hash:
    path: /_fos_user_context_hash
```

--------------------------------

### Configure Cache Header Rules with Attributes

Source: https://github.com/friendsofsymfony/foshttpcachebundle/wiki/Migrating-from-LiipCacheControlBundle

Use the 'attributes' parameter to match on routing attributes, such as '_controller'. This replaces the older 'controller' parameter.

```yaml
fos_http_cache:
    rules:
        - 
            attributes:
                _controller: "^acme\.controller.*"
            ...
```

--------------------------------

### Configure Varnish Base URL with Port

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Set the base URL for Varnish invalidation requests, including a specific port if your application does not run on the default port 80. Double-check for typos to ensure correct invalidation.

```yaml
fos_http_cache:
    proxy_client:
        varnish:
            http:
                base_url: yourwebsite.com:8000
```

--------------------------------

### Configure URL Generation Type

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/general.rst

Set the reference type for generating URLs. Use ABSOLUTE_PATH for paths only, requiring 'base_url' configuration on the proxy client. 'auto' determines the value dynamically.

```yaml
# app/config/config.yml
fos_http_cache:
    generate_url_type: !php/const Symfony\Component\Routing\Generator\UrlGeneratorInterface::ABSOLUTE_PATH
```

--------------------------------

### Configure Custom Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/cache-manager.rst

Specify a custom service ID for the proxy client if you are not using the bundle's default proxy client configuration. The bundle will not know the capabilities of a custom client.

```yaml
fos_http_cache:
    cache_manager:
        custom_proxy_client: acme.caching.proxy_client
```

--------------------------------

### Enable Cache Tagging Configuration

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/tagging.rst

Enable the cache tagging feature in your application's configuration.

```yaml
fos_http_cache:
    tags:
        enabled: true
```

--------------------------------

### Set Default Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the default proxy client if you have multiple proxy clients defined. This specifies which client the cache manager will use.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        default: varnish
```

--------------------------------

### Implement Custom Cache Manager Logic

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/invalidation.rst

For complex cache interactions, create your own commands and leverage the cache manager. This allows for specific cache invalidation strategies tailored to your application's needs.

```php
<?php

namespace App\Command;

use FOS\HttpCacheBundle\CacheManager\CacheManager;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class MyCustomInvalidationCommand extends Command
{
    protected static $defaultName = 'app:my-custom-invalidation';

    private CacheManager $cacheManager;

    public function __construct(CacheManager $cacheManager)
    {
        parent::__construct();
        $this->cacheManager = $cacheManager;
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Implement your specific cache invalidation logic here
        // For example, invalidating by tag:
        $this->cacheManager->invalidateTag('some_tag');

        // Or invalidating a specific URL:
        // $this->cacheManager->invalidatePath('/some/url');

        $output->writeln('Custom invalidation complete.');

        return Command::SUCCESS;
    }
}

```

--------------------------------

### Configure Custom Reverse Proxy TTL

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Set a custom TTL header for reverse proxy timeouts not driven by s-maxage. Requires proxy configuration to respect this header.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                headers:
                    reverse_proxy_ttl: 3600
                    cache_control:
                        public: true
                        s_maxage: 60
```

--------------------------------

### Cache Control Rules Configuration

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Defines default cache control settings and specific rules for matching requests and setting headers. Rules are checked in order, and the first match wins. Overwrite options can be set globally or per rule.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        defaults:
            overwrite: false
        rules:
            # only match login.example.com
            - 
                match:
                    host: ^login.example.com$
                headers:
                    overwrite: true
                    cache_control:
                        public: false
                        max_age: 0
                        s_maxage: 0
                    etag: true
                    vary: [Accept-Encoding, Accept-Language]

            # match all actions of a specific controller
            - 
                match:
                    attributes: { _controller: ^Acme\\TestBundle\\Controller\\DefaultController::.* }
                headers:
                    cache_control:
                        public: true
                        max_age: 15
                        s_maxage: 30
                    last_modified: "-1 hour"

            - 
                match:
                    path: ^/$
                headers:
                    cache_control:
                        public: true
                        max_age: 64000
                        s_maxage: 64000
                    etag: true
                    vary: [Accept-Encoding, Accept-Language]

            # match everything to set defaults
            - 
                match:
                    path: ^/
                    additional_response_status:
                        - 500
                headers:
                    cache_control:
                        public: true
                        max_age: 15
                        s_maxage: 30
                    etag: true

```

--------------------------------

### Extend ProxyTestCase for Cache Testing

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/testing.rst

Extend your test classes from ProxyTestCase to test application caching and invalidation strategies against a live Varnish or Nginx instance. Use assertMiss and assertHit to verify cache behavior.

```php
use FOS\HttpCache\Test\ProxyTestCase;

class YourTest extends ProxyTestCase
{
    public function testCachingHeaders()
    {
        // Retrieve an URL from your application
        $response = $this->getResponse('/your/page');

        // Assert the response was a cache miss (came from the backend
        // application)
        $this->assertMiss($response);

        // Assume the URL /your/page sets caching headers. If we retrieve
        // it again, we should have a cache hit (response delivered by the
        // caching proxy):
        $response = $this->getResponse('/your/page');
        $this->assertHit($response);
    }
}
```

--------------------------------

### Configure HTTP Caching Headers with Rules

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/headers.rst

Use this configuration to define rules for setting HTTP caching headers. Each rule can match specific request properties (host, controller, query string, path) and apply corresponding headers to the response. Overwriting existing headers can be controlled globally or per rule.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        defaults:
            overwrite: true
        rules:
            # only match login.example.com
            - 
                match:
                    host: ^login.example.com$
                headers:
                    cache_control: { public: false, max_age: 0, s_maxage: 0 }
                    etag: "strong"
                    vary: [Accept-Encoding, Accept-Language]

            # match all actions of a specific controller
            - 
                match:
                    attributes: { _controller: ^AcmeBundle:Default:.* }
                headers:
                    cache_control: { public: true, max_age: 15, s_maxage: 30 }
                    last_modified: "-1 hour"

            # only match URLs having a specific parameter
            - 
                match:
                    query_string: (^|&)token=
                headers:
                    cache_control: { public: false, max_age: 0, s_maxage: 0 }

            - 
                match:
                    path: ^/$
                headers:
                    cache_control: { public: true, max_age: 64000, s_maxage: 64000 }
                    etag: "strong"
                    vary: [Accept-Encoding, Accept-Language]

            # match everything to set defaults
            - 
                match:
                    path: ^/
                headers:
                    overwrite: false
                    cache_control: { public: true, max_age: 15, s_maxage: 30 }
                    etag: "strong"
```

--------------------------------

### Configure Flash Message Listener

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/flash-message.rst

Enable and configure the flash message listener in app/config/config.yml. The subscriber is automatically enabled when any option is configured.

```yaml
# app/config/config.yml
fos_http_cache:
    flash_message:
        enabled: true
        name: flashes
        path: /
        host: null
        secure: false
```

--------------------------------

### Enable User Context Subscriber

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Explicitly enable the user context subscriber by setting 'enabled' to true. This is automatically enabled if any 'user_context' options are configured.

```yaml
# app/config/config.yml
fos_http_cache:
    user_context:
        enabled: true
```

--------------------------------

### Configure Tagging Rules

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/tagging.rst

Define rules in configuration to automatically set or invalidate tags based on request path matching. Safe requests set tags, unsafe requests invalidate them.

```yaml
// app/config/config.yml
fos_http_cache:
    tags:
        rules:
            - 
                match:
                    path: ^/news/article
                tags: [news]
```

--------------------------------

### Match Multiple Route Names

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Apply caching rules to multiple routes by using a regular expression that matches various route names.

```yaml
match:
    attributes:
        _route: ^articles.*|news$
```

--------------------------------

### Match Query String for Specific Token Value

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Use this configuration to test if a 'token' parameter exists and has the specific value 'foo'.

```yaml
match:
    query_string: (^|&)token=foo(&|$)
```

--------------------------------

### Configure Strong ETag

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Enable strong ETag generation for cache validation.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                headers:
                    etag: "strong"
```

--------------------------------

### Implement HttpCacheProvider in AppKernel

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/symfony-http-cache.rst

Implement the HttpCacheProvider interface and use the HttpCacheAware trait in your AppKernel to provide the cache instance, recommended for kernel dispatcher optimization.

```php
namespace App;

use FOS\HttpCache\SymfonyCache\HttpCacheAware;
use FOS\HttpCache\SymfonyCache\HttpCacheProvider;
use Symfony\Component\HttpKernel\Kernel;

class AppKernel extends Kernel implements HttpCacheProvider
{
    use HttpCacheAware;
    // ...

    public function __construct(...)
    {
        // ...
        $this->setHttpCache(new AppCache($this));
    }
}
```

--------------------------------

### Configure Advanced Cache Control Directives

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Utilize advanced cache control directives like stale-while-revalidate and stale-if-error for specific paths.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                path: ^/
                headers:
                    cache_control:
                        stale_while_revalidate: 9000
                        stale_if_error: 3000
                        must_revalidate: true
                        proxy_revalidate: true
                        no_transform: true
```

--------------------------------

### fos:httpcache:refresh:path Console Command

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/invalidation.rst

Command-line tool to refresh one or more paths, fetching fresh content from the backend. Useful for updating cached content without full invalidation.

```bash
php app/console fos:httpcache:refresh:path /users
```

--------------------------------

### Enable Role-Based User Context

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Enable caching differentiation based on user roles. This requires a security context that can provide the user's roles.

```yaml
app/config/config.yml
fos_http_cache
    user_context:
        role_provider: true
```

--------------------------------

### Configure Nginx Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the Nginx proxy client for cache invalidation. Specify the purge location and HTTP server details.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        nginx:
            purge_location: /purge
            http:
                servers:
                    - 123.123.123.1:6060
                    - 123.123.123.2
                base_url: yourwebsite.com
```

--------------------------------

### Configure Vary Header Rule

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Set a custom Vary header for cache matching. This adds to existing Vary headers.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                headers:
                    vary: My-Custom-Header
```

--------------------------------

### Configure Last-Modified Header

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Set the Last-Modified header with a relative time string for cache validation.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                headers:
                    last_modified: "-1 hour"
```

--------------------------------

### Configure FOSRestBundle Format Listener for Hash Route

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/user-context.rst

Add a rule to the FOSRestBundle format listener to prevent '406 Not Acceptable' errors for the user context hash route. This ensures the hash lookup functions correctly.

```yaml
- { path: '^/_fos_user_context_hash', stop: true }
```

--------------------------------

### Enable Strict Mode for Tagging

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/tags.rst

Set this to true to throw an exception when an empty or null tag is added. This enforces stricter tag management.

```yaml
# app/config/config.yml
fos_http_cache:
    tags:
        strict: true
```

--------------------------------

### Configure Symfony HttpCache Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the Symfony HttpCache proxy client. Customize cache tag headers, methods, and HTTP server details. Optionally use kernel dispatcher.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        symfony:
            tags_header: My-Cache-Tags
            tags_method: TAGPURGE
            header_length: 1234
            purge_method: PURGE
            # for single server installations:
            # use_kernel_dispatcher: true
            http:
                servers:
                    - 123.123.123.1:6060
                    - 123.123.123.2
                base_url: yourwebsite.com
```

--------------------------------

### Enable Role Provider for Hash Generation

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/user-context.rst

Enable the default role provider to generate user context hashes based on the user's roles. This is a simple way to vary cache based on user permissions.

```yaml
fos_http_cache:
    user_context:
        role_provider: true
```

--------------------------------

### Match Query String for Token Parameter

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

This snippet demonstrates how to match requests that have a 'token' parameter in the query string.

```yaml
match:
    query_string: (^|&)token=
```

--------------------------------

### Enable Debug Header in FOSHttpCacheBundle

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/debug.rst

Enable debug mode to set a custom header (X-Cache-Debug) on responses. Configure your caching proxy to add debug information when this header is present. The 'enabled' parameter defaults to '%kernel.debug%', activating the header in 'dev' mode but not 'prod' mode. The 'header' parameter allows customization of the header name.

```yaml
# app/config/config.yml
fos_http_cache:
    debug:
        enabled: true
        header: Please-Send-Debug-Infos
```

--------------------------------

### Configure Public Cache Control

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/headers.rst

Set cache control headers to public with a max age for all requests.

```yaml
# app/config/config.yml
fos_http_cache:
    cache_control:
        rules:
            - 
                headers:
                    cache_control:
                        public: true
                        max_age: 64000
                        s_maxage: 64000
```

--------------------------------

### Configure User Identifier Headers and Cache TTL

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/user-context.rst

Specify HTTP headers for varying cache based on user context and set the cache time-to-live. The 'Cookie' header is automatically included unless session name prefix is disabled.

```yaml
app/config/config.yml
fos_http_cache:
    user_context:
        user_identifier_headers:
            - Authorization
        hash_cache_ttl: 900
```

--------------------------------

### Console Commands for Invalidation

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/invalidation.rst

Provides command-line tools to perform cache invalidation and refreshing tasks.

```APIDOC
## Console Commands for Invalidation

### Description
Execute cache invalidation and refresh operations directly from the command line using provided bundle commands.

### Commands

- `fos:httpcache:invalidate:path`
  - **Description**: Invalidates one or more specified paths.
  - **Usage**: `php bin/console fos:httpcache:invalidate:path /path/to/resource1 /path/to/resource2`

- `fos:httpcache:refresh:path`
  - **Description**: Refreshes one or more specified paths.
  - **Usage**: `php bin/console fos:httpcache:refresh:path /path/to/resource`

- `fos:httpcache:invalidate:regex`
  - **Description**: Invalidates all cache entries matching a given regular expression.
  - **Usage**: `php bin/console fos:httpcache:invalidate:regex ".*"` (to invalidate entire cache)
  - **Usage with content type**: `php bin/console fos:httpcache:invalidate:regex ".*\.png$" image/png`
```

--------------------------------

### Match Single Route Name

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Configure caching rules to apply only to a specific route identified by its name.

```yaml
match:
    attributes:
        _route: ^articles_index$
```

--------------------------------

### Apply Multiple Tags to a Response

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/attributes.rst

Use multiple Tag attributes or a single attribute with an array to apply multiple tags to a response. This allows for more granular cache control.

```php
use FOS\HttpCacheBundle\Configuration\Tag;

#[Tag('news')]
#[Tag('news-list')]
public function indexAction()
{
    // ...
}
```

```php
use FOS\HttpCacheBundle\Configuration\Tag;

#[Tag(['news-article', 'news-list'])]
```

--------------------------------

### Configure Security Access Control for User Context

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/features/user-context.rst

Ensure the user context hash route is accessible by anonymous users, especially if the rest of the site requires authentication. This prevents caching lookups from failing.

```yaml
access_control:
    - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
    - { path: ^/_fos_user_context_hash, roles: [IS_AUTHENTICATED_ANONYMOUSLY] }
    - { path: ^/, roles: ROLE_USER }
```

--------------------------------

### Match Request Client IP Addresses

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Define rules to be applied only to requests originating from specific client IP addresses.

```yaml
match:
    ips: [192.168.0.1, 10.0.0.0/8]
```

--------------------------------

### Tag Responses Using Expressions

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/attributes.rst

Utilize expressions within the Tag attribute to dynamically generate tags based on request parameters or object properties. This enables context-aware tagging.

```php
use FOS\HttpCacheBundle\Configuration\Tag;

#[Tag(expression: "'news-'~id")]
public function showAction($id)
{
    // Assume request parameter $id equals 123
}
```

```php
use FOS\HttpCacheBundle\Configuration\Tag;

#[Tag(expression: "'news-'~article.getId()")]
public function showAction(Article $article)
{
    // Assume $article->getId() returns 123
}
```

--------------------------------

### Enable Cache Manager Automatically

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/cache-manager.rst

Set the cache manager to 'auto' to enable it when a proxy client is configured. This is the default behavior.

```yaml
fos_http_cache:
    cache_manager:
        enabled: auto
```

--------------------------------

### Refresh a URL

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/cache-manager.rst

Refresh a specific URL by passing the full URL to refreshPath().

```php
$cacheManager->refreshPath('http://www.example.com/users');
```

--------------------------------

### Configure Expression Language for Tags

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/tags.rst

Specify a custom expression language service to use for dynamic tag generation. This allows for more complex tag definitions based on request attributes.

```yaml
# app/config/config.yml
fos_http_cache:
    tags:
        expression_language: app.expression_language
```

--------------------------------

### Match Specific HTTP Methods

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/match.rst

Limit caching rules to specific HTTP methods like PUT and DELETE. Note that unsafe methods are not cached even if specified.

```yaml
match:
    methods: [PUT, DELETE]
```

--------------------------------

### Configure Cloudflare Proxy Client

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/configuration/proxy-client.rst

Configure the Cloudflare proxy client for cache invalidation. Provide zone identifier and authentication token for API access.

```yaml
# config/packages/fos_http_cache.yaml
fos_http_cache:
    proxy_client:
        cloudflare:
            zone_identifier: '<my-zone-identifier>'
            authentication_token: '<user-authentication-token>'
            http:
                servers:
                    - 'https://api.cloudflare.com'
```

--------------------------------

### Cache Manager Refreshing

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/cache-manager.rst

Methods for refreshing cache content. Ensure your proxy is configured for purging before using these methods.

```APIDOC
## Refresh Cache Content

### Description
Methods to refresh cache entries for specific paths, URLs, or routes. Refreshing fetches a fresh copy of the content immediately.

### Methods
- `refreshPath(string $path)`: Refreshes a specific path.
- `refreshRoute(string $routeName, array $params = [])`: Refreshes a route with given parameters.

### Request Example (Refresh Path)
```php
$cacheManager->refreshPath('/users');
```

### Request Example (Refresh URL)
```php
$cacheManager->refreshPath('http://www.example.com/users');
```

### Request Example (Refresh Route)
```php
$cacheManager->refreshRoute('user_details', array('id' => 123));
```
```

--------------------------------

### Manually Flush the Cache Manager

Source: https://github.com/friendsofsymfony/foshttpcachebundle/blob/3.x/Resources/doc/reference/cache-manager.rst

Manually trigger the flushing of queued invalidation requests to the HTTP proxy. The manager usually flushes automatically.

```php
$cacheManager->flush();
```