From af4123236bc47820d63a9a769a2d94c91e14bf07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Berislav=20Balogovi=C4=87?= Date: Thu, 24 Oct 2024 12:46:22 +0200 Subject: [PATCH] Add docs --- README.md | 49 ++++++++++++++++++++--------- docs/README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 15 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 9996a93..398d2ba 100644 --- a/README.md +++ b/README.md @@ -5,27 +5,46 @@ [![Code Coverage](https://codecov.io/gh/sofascore/purgatory-bundle/graph/badge.svg?token=HWMVLVSTIC)](https://codecov.io/gh/sofascore/purgatory-bundle) [![License](https://poser.pugx.org/sofascore/purgatory-bundle/license)](https://packagist.org/packages/sofascore/purgatory-bundle) -A Symfony bundle for creating and sending cache purge requests to HTTP cache backends like Varnish. +A Symfony bundle designed to automatically generate and send cache purge requests to HTTP cache backends like Varnish. +It leverages Doctrine events to detect changes in entities and generates URLs that need to be purged based on configured +routes. ## Features -* TODO +- **Doctrine Event Integration**: Listens to **Doctrine** lifecycle events (`postUpdate`, `postRemove`, `postPersist`) + to automatically detect when entities are modified, created, or deleted. + +- **Automatic URL Generation**: Automatically generates purge requests for relevant URLs based on the affected entities + and their associated routes. + +- **Flexible Configuration**: + - Primary configuration is through the PHP attribute, `#[PurgeOn]`, allowing you to directly annotate entity classes + with cache purge rules. + - Supports YAML configuration for flexibility depending on your project’s requirements. + +- **Built-in Purger Support**: Comes with built-in support for **Symfony HTTP Cache** and a basic **Varnish** + implementation. For advanced use cases, you can create custom purgers by implementing the `PurgerInterface`. + +- **Asynchronous Processing with Symfony Messenger**: Includes built-in support for **Symfony Messenger** to process + purge requests asynchronously for better scalability and efficiency. ## Requirements -* [PHP 8.1](http://php.net/releases/8_1_0.php) or greater -* [Symfony 5.4](https://symfony.com/roadmap/5.4) or [Symfony 6.4](https://symfony.com/roadmap/6.4) or greater +- [PHP 8.1](http://php.net/releases/8_1_0.php) or higher +- [Symfony 5.4](https://symfony.com/roadmap/5.4) or [Symfony 6.4](https://symfony.com/roadmap/6.4) or higher ## Installation -1. Require the bundle with [Composer](https://getcomposer.org/): +Require the bundle using [Composer](https://getcomposer.org/): - ```sh - composer require sofascore/purgatory-bundle - ``` +```sh +composer require sofascore/purgatory-bundle +``` + +If your project doesn't use [Symfony Flex](https://github.com/symfony/flex), continue with the following steps. -1. Create the bundle configuration file under `config/packages/purgatory.yaml`. Here is a reference - configuration file: +1. Create a configuration file under `config/packages/purgatory.yaml`. Here's a reference + configuration: ```yaml purgatory: @@ -86,16 +105,16 @@ A Symfony bundle for creating and sending cache purge requests to HTTP cache bac ## Usage -TODO +For detailed instructions and examples, refer to the [documentation](/docs/). ## Versioning -This project adheres to [Semantic Versioning 2.0.0](http://semver.org/). +This project follows [Semantic Versioning 2.0.0](http://semver.org/). -## Reporting issues +## Reporting Issues -Use the [issue tracker](https://github.com/sofascore/purgatory-bundle/issues) to report any issues you might have. +Use the [issue tracker](https://github.com/sofascore/purgatory-bundle/issues) to report any issues you encounter. ## License -See the [LICENSE](LICENSE) file for license rights and limitations (MIT). +See the [LICENSE](LICENSE) file for details (MIT). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8eaa806 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,85 @@ +# Getting Started + +The bundle is designed to automatically generate and send cache purge requests to HTTP cache backends such as Symfony's +HTTP cache or Varnish. It leverages Doctrine events to detect changes in entities and generates URLs that need to be +purged based on configured routes. + +## Why URL-based Invalidation? + +This bundle uses URL-based invalidation instead of tag-based invalidation due to the following reasons: + +1. **Performance Concerns**: Varnish's tag-based invalidation can lead to slow responses when multiple URLs are + invalidated simultaneously. +1. **Header Size Limitations**: Tags are typically passed through HTTP headers, which have size limitations. This means + not all tags may fit within the header limits. +1. **Cost Implications**: Some CDN providers charge extra for tag-based invalidation, making URL-based purging a more + cost-effective solution. + +## Supported Backends + +The bundle includes built-in support for [Symfony HTTP Cache](https://symfony.com/doc/current/http_cache.html) and a +basic [Varnish](https://varnish-cache.org/) implementation. Each backend is realized by implementing +the [`PurgerInterface`](/src/Purger/PurgerInterface.php). + +It also comes with a `VoidPurger`, which can be used during development when cache purging is not required. The +`VoidPurger` simply ignores all purge requests, making it ideal for non-production environments. Additionally, an +`InMemoryPurger` is provided, designed specifically for testing purposes. The `InMemoryPurger` simulates purging actions +without interacting with external cache services, enabling you to verify your purging logic in tests. + +For advanced use cases, you can create custom purgers by implementing the `PurgerInterface`. This allows you to +integrate with any custom or third-party HTTP cache backend that fits your project requirements. + +### Configuring Symfony's HTTP Cache + +Configure Symfony's HTTP Cache following +the [official documentation](https://symfony.com/doc/current/http_cache.html#symfony-reverse-proxy). + +Enable the Symfony purger with the following configuration: + +```yaml +purgatory: + purger: symfony +``` + +### Configuring Varnish Cache + +To enable Varnish to support PURGE requests, add the following example configuration to your VCL file. You may need to +customize it based on your specific Varnish setup: + +```vcl +acl purge { + "localhost"; + "172.16.0.0"/12; # Common Docker IP range, adjust as needed + # Add more whitelisted IPs here +} + +sub vcl_recv { + if (req.method == "PURGE") { + if (client.ip !~ purge) { + return (synth(405, "Not allowed.")); + } + return (purge); + } +} +``` + +Enable the Varnish purger with the following configuration: + +```yaml +purgatory: + purger: varnish +``` + +Optionally, you can specify a list of Varnish hosts: + +```yaml +purgatory: + purger: + name: varnish + hosts: + - varnish1.example.com + - varnish2.example.com + - varnish3.example.com +``` + +If no hosts are specified, the bundle will use the host from the URL.