Add docs

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).

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.