update subscriber cleanup docs & add some tests

Author: DavidBadura

docs/pages/subscription.md

@@ -299,7 +299,7 @@ final class DoStuffSubscriber
 You can provide your own argument resolvers by implementing the `ArgumentResolver` interface.
 This can be useful for providing direct access to custom headers or other data.
 
-### Setup and Teardown
+### Setup
 
 Subscribers can have one `setup` method that is executed when the subscription is created.
 For this there is the attributes `Setup`. The method name itself doesn't matter.
@@ -377,16 +377,20 @@ final class ProfileProjector
 
 !!! warning
 
-    A teardown can only be performed for a subscription if the subscriber with that subscriber ID still exists.
+    A teardown can only be performed for a subscription if the code for the subscriber with that subscriber ID still exists.
+    A another option is to use the `Cleanup` option.
 
 !!! note
 
     You can not mix the `cleanup` method with the `teardown` method.
 
 ### Cleanup
 
-The cleanup option allows you to delete the subscription from the database after the subscription has finished.
-This is especially useful for projectors,
+Alternativ, you can use a `cleanup` method for cleanup tasks.
+Unlike Teardown, this method is called when the subscription is created.
+The tasks are then saved in the Subscription Store.
+When removing the subscription, the subscriber is not necessary anymore, 
+as the cleanup can be performed using the tasks in the store and an associated external handler.
 
 ```php
 use Doctrine\DBAL\Connection;
@@ -416,9 +420,18 @@ final class ProfileProjector
 
     You can not mix the `cleanup` method with the `teardown` method.
 
+#### Dbal Cleanup Tasks
+
+Default, we provide the following cleanup tasks for `doctrine/dbal`:
+
+| Task            | Description                  |
+|-----------------|------------------------------|
+| `DropIndexTask` | Drops an index from a table. |
+| `DropTableTask` | Drops a table.               |
+
 !!! tip
 
-    You can create your own cleanup tasks and add them to the array.
+    You can create your own cleanup tasks and handler.
     For more information, see [Cleanup Handler](#cleanup-handler).
 
 ### On Failed
@@ -998,11 +1011,9 @@ $retryStrategyRepository = new RetryStrategyRepository([
 
 ### Cleanup Handler
 
-You can also create your own cleanup tasks.
-The subscription engine will call the method `__invoke` on the task object.
-For example, you can create a task that drops a collection from a MongoDB database.
-
-First, create a task class, that holds the collection name.
+You can also create your own cleanup tasks with associated handlers.
+First, create a task class that has all necessary information for the task.
+In our example, we create a task that deletes a collection from MongoDB.
 
 ```php
 final class DropCollection {
@@ -1016,7 +1027,8 @@ final class DropCollection {
 
     The task class must be serializable. It will be stored in the subscription store.
 
-Then create a handler that supports this task.
+The next step is to create a handler for the task. 
+The handler must implement the `CleanupHandler` interface.
 
 ```php
 use MongoDb\Database;
@@ -1041,7 +1053,8 @@ final class MongodbCleanupHandler implements CleanupHandler {
 }
 ```
 
-Last step, you need to add the handler to the `DefaultCleaner`, that is used by the subscription engine.
+Lastly, we have to add the new handler to `DefaultCleaner`,
+which is responsible for cleaning up subscriptions.
 
 ```php
 use Patchlevel\EventSourcing\Subscription\Cleanup\DefaultCleaner;
@@ -1052,6 +1065,10 @@ $cleaner = new DefaultCleaner([
 ]);
 ```
 
+!!! warning
+
+    You need to pass the Cleaner to the Subscription Engine.
+
 ### Subscriber Accessor
 
 The subscriber accessor repository is responsible for providing the subscribers to the subscription engine.
@@ -1105,7 +1122,7 @@ $subscriptionEngine = new DefaultSubscriptionEngine(
     $logger, // optional
     new DefaultCleaner([
         new DbalCleanupHandler($projectionConnection)
-    ]), // required, if you want to use the cleanup feature
+    ]), // optional but required if you want to use the cleanup feature
 );
 ```
 ### Catch up Subscription Engine

src/Subscription/Cleanup/DefaultCleaner.php

@@ -11,7 +11,7 @@ final class DefaultCleaner implements Cleaner
 {
     /** @param iterable<CleanupHandler> $handlers */
     public function __construct(
-        private readonly iterable $handlers,
+        private readonly iterable $handlers = [],
     ) {
     }
 

src/Subscription/Engine/CleanerNotConfigured.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Subscription\Engine;
+
+use RuntimeException;
+
+final class CleanerNotConfigured extends RuntimeException
+{
+    public function __construct()
+    {
+        parent::__construct('Cleaner not configured.');
+    }
+}

src/Subscription/Engine/DefaultSubscriptionEngine.php

@@ -25,6 +25,7 @@
 use Psr\Log\LoggerInterface;
 use Throwable;
 
+use function array_values;
 use function count;
 use function sprintf;
 
@@ -1245,7 +1246,7 @@ private function retryStrategy(Subscription $subscription): RetryStrategy
     private function cleanup(Subscription $subscription): Error|null
     {
         if (!$this->cleaner) {
-            throw new UnexpectedError('Cleaner is not configured.');
+            throw new CleanerNotConfigured();
         }
 
         try {
@@ -1295,6 +1296,10 @@ private function cleanupTasks(SubscriberAccessor $subscriber): array|null
             return null;
         }
 
+        if (!$this->cleaner) {
+            throw new CleanerNotConfigured();
+        }
+
         return array_values([...$method()]);
     }
 }

tests/Integration/Subscription/SubscriptionTest.php

@@ -1185,6 +1185,12 @@ public function testCleanup(): void
     {
         // Test Setup
 
+        $cleaner = new DefaultCleaner([
+            new DbalCleanupHandler(
+                $this->projectionConnection,
+            ),
+        ]);
+
         $store = new DoctrineDbalStore(
             $this->connection,
             DefaultEventSerializer::createFromPaths([__DIR__ . '/Events']),
@@ -1218,6 +1224,7 @@ public function testCleanup(): void
             $store,
             $subscriptionStore,
             new MetadataSubscriberAccessorRepository([new ProfileProjectionWithCleanup($this->projectionConnection)]),
+            cleaner: $cleaner,
         );
 
         // Deploy first version
@@ -1267,11 +1274,7 @@ public function testCleanup(): void
             $store,
             $subscriptionStore,
             new MetadataSubscriberAccessorRepository([new ProfileNewProjection($this->projectionConnection)]),
-            cleaner: new DefaultCleaner([
-                new DbalCleanupHandler(
-                    $this->projectionConnection,
-                ),
-            ]),
+            cleaner: $cleaner,
         );
 
         $secondEngine->setup();

tests/Unit/Subscription/Cleanup/DefaultCleanerTest.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Unit\Subscription\Cleanup;
+
+use Patchlevel\EventSourcing\Subscription\Cleanup\CleanupHandler;
+use Patchlevel\EventSourcing\Subscription\Cleanup\Dbal\DropTableTask;
+use Patchlevel\EventSourcing\Subscription\Cleanup\DefaultCleaner;
+use Patchlevel\EventSourcing\Subscription\Cleanup\NoHandlerForCleanupTask;
+use Patchlevel\EventSourcing\Subscription\Subscription;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+#[CoversClass(DefaultCleaner::class)]
+final class DefaultCleanerTest extends TestCase
+{
+    public function testClean(): void
+    {
+        $handler = new class implements CleanupHandler {
+            public bool $called = false;
+
+            public function __invoke(object $task): void
+            {
+                $this->called = true;
+            }
+
+            public function supports(object $task): bool
+            {
+                return true;
+            }
+        };
+
+        $cleaner = new DefaultCleaner([$handler]);
+        $cleaner->cleanup(
+            new Subscription('test', cleanupTasks: [new DropTableTask('test')]),
+        );
+
+        self::assertTrue($handler->called);
+    }
+
+    public function testCleanupFailed(): void
+    {
+        $handler = new class implements CleanupHandler {
+            public function __invoke(object $task): void
+            {
+                throw new RuntimeException('Failed to cleanup');
+            }
+
+            public function supports(object $task): bool
+            {
+                return true;
+            }
+        };
+
+        $cleaner = new DefaultCleaner([$handler]);
+        $this->expectException(RuntimeException::class);
+
+        $cleaner->cleanup(
+            new Subscription('test', cleanupTasks: [new DropTableTask('test')]),
+        );
+    }
+
+    public function testNoTasks(): void
+    {
+        $handler = new class implements CleanupHandler {
+            public bool $called = false;
+
+            public function __invoke(object $task): void
+            {
+                $this->called = true;
+            }
+
+            public function supports(object $task): bool
+            {
+                return true;
+            }
+        };
+
+        $cleaner = new DefaultCleaner([$handler]);
+        $cleaner->cleanup(new Subscription('test'));
+
+        self::assertTrue($handler->called === false);
+    }
+
+    public function testNoHandler(): void
+    {
+        $this->expectException(NoHandlerForCleanupTask::class);
+
+        $cleaner = new DefaultCleaner();
+        $cleaner->cleanup(
+            new Subscription('test', cleanupTasks: [new DropTableTask('test')]),
+        );
+    }
+}