Merge release 3.20.0 into 4.0.x

.github/workflows/backward-compatibility-check.yml

@@ -22,7 +22,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 

.github/workflows/benchmark.yml

@@ -46,7 +46,7 @@ jobs:
           extensions: pdo_sqlite
 
       - name: "Checkout base"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           ref: ${{ github.base_ref }}
 
@@ -58,7 +58,7 @@ jobs:
         run: "vendor/bin/phpbench run tests/Benchmark --progress=none --report=default --tag=base"
 
       - name: "Checkout"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           clean: false
 

.github/workflows/coding-standard.yml

@@ -26,7 +26,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Install PHP"
               uses: "shivammathur/setup-php@2.37.2"

.github/workflows/docs-check.yml

@@ -0,0 +1,48 @@
+# https://help.github.com/en/categories/automating-your-workflow-with-github-actions
+
+name: "Check Docs"
+
+on:
+    pull_request:
+    push:
+        branches:
+            - "[0-9]+.[0-9]+.x"
+
+jobs:
+    checkdocs:
+        name: "Check Docs"
+
+        runs-on: ${{ matrix.operating-system }}
+
+        strategy:
+            matrix:
+                dependencies:
+                    - "locked"
+                php-version:
+                    - "8.4"
+                operating-system:
+                    - "ubuntu-latest"
+
+        steps:
+            - name: "Checkout"
+              uses: actions/checkout@v7
+
+            - name: "Install PHP"
+              uses: "shivammathur/setup-php@2.37.2"
+              with:
+                  coverage: none
+                  php-version: "${{ matrix.php-version }}"
+                  ini-values: memory_limit=-1, opcache.enable_cli=1
+
+            - uses: ramsey/composer-install@4.0.0
+              with:
+                dependency-versions: ${{ matrix.dependencies }}
+
+            - name: "extract php code"
+              run: "bin/docs-extract-php-code"
+
+            - name: "lint php"
+              run: "php -l docs_php/*.php"
+
+            - name: "docs code style"
+              run: "vendor/bin/phpcbf docs_php --exclude=SlevomatCodingStandard.TypeHints.DeclareStrictTypes"

.github/workflows/integration.yml

@@ -48,7 +48,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Install PHP"
               uses: "shivammathur/setup-php@2.37.2"
@@ -103,7 +103,7 @@ jobs:
 
       steps:
         - name: "Checkout"
-          uses: actions/checkout@v6
+          uses: actions/checkout@v7
 
         - name: "Install PHP"
           uses: "shivammathur/setup-php@2.37.2"
@@ -157,7 +157,7 @@ jobs:
 
       steps:
         - name: "Checkout"
-          uses: actions/checkout@v6
+          uses: actions/checkout@v7
 
         - name: "Install PHP"
           uses: "shivammathur/setup-php@2.37.2"
@@ -191,7 +191,7 @@ jobs:
 
       steps:
         - name: "Checkout"
-          uses: actions/checkout@v6
+          uses: actions/checkout@v7
 
         - name: "Install PHP"
           uses: "shivammathur/setup-php@2.37.2"

.github/workflows/mutation-tests-diff.yml

@@ -22,7 +22,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
               with:
                 fetch-depth: 0
 

.github/workflows/mutation-tests.yml

@@ -26,7 +26,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Install PHP"
               uses: "shivammathur/setup-php@2.37.2"

.github/workflows/phpstan.yml

@@ -26,7 +26,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Install PHP"
               uses: "shivammathur/setup-php@2.37.2"

.github/workflows/release-on-milestone-closed-triggering-release-event.yml

@@ -18,7 +18,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Release"
               uses: "laminas/automatic-releases@v1"

.github/workflows/unit.yml

@@ -38,7 +38,7 @@ jobs:
 
         steps:
             - name: "Checkout"
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
 
             - name: "Install PHP"
               uses: "shivammathur/setup-php@2.37.2"

bin/docs-extract-php-code

@@ -3,6 +3,8 @@
 
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Extension\FrontMatter\Data\FrontMatterDataParserInterface;
+use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
 use League\CommonMark\Node\Query;
 use League\CommonMark\Parser\MarkdownParser;
 use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
@@ -11,6 +13,15 @@ require __DIR__ . '/../vendor/autoload.php';
 
 $environment = new Environment([]);
 $environment->addExtension(new MarkdownRendererExtension());
+$environment->addExtension(new FrontMatterExtension(
+    // keep the raw YAML string so it round-trips byte-identically
+    new class implements FrontMatterDataParserInterface {
+        public function parse(string $frontMatter): string
+        {
+            return $frontMatter;
+        }
+    },
+));
 
 $parser = new MarkdownParser($environment);
 

bin/docs-inject-php-code

@@ -3,6 +3,9 @@
 
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Extension\FrontMatter\Data\FrontMatterDataParserInterface;
+use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
+use League\CommonMark\Extension\FrontMatter\Output\RenderedContentWithFrontMatter;
 use League\CommonMark\Node\Query;
 use League\CommonMark\Parser\MarkdownParser;
 use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
@@ -14,6 +17,15 @@ require __DIR__ . '/../vendor/autoload.php';
 
 $environment = new Environment([]);
 $environment->addExtension(new MarkdownRendererExtension());
+$environment->addExtension(new FrontMatterExtension(
+    // keep the raw YAML string so it round-trips byte-identically
+    new class implements FrontMatterDataParserInterface {
+        public function parse(string $frontMatter): string
+        {
+            return $frontMatter;
+        }
+    },
+));
 
 $parser = new MarkdownParser($environment);
 $markdownRenderer = new MarkdownRenderer($environment);
@@ -62,7 +74,14 @@ foreach ($finder as $file) {
         $node->setLiteral(trim($code));
     }
 
-    file_put_contents($file->getPathname(), $markdownRenderer->renderDocument($document));
+    $rendered = $markdownRenderer->renderDocument($document);
+    $output = $rendered->getContent();
+
+    if ($rendered instanceof RenderedContentWithFrontMatter) {
+        $output = $rendered->getFrontMatter() . "---\n" . $output;
+    }
+
+    file_put_contents($file->getPathname(), $output);
 }
 
 if (file_exists($targetDir)) {

docker-compose.yaml

@@ -25,3 +25,11 @@ services:
       - MYSQL_DATABASE=eventstore
     ports:
       - 3306:3306
+
+  mariadb:
+    image: mariadb:12
+    environment:
+      - MYSQL_ALLOW_EMPTY_PASSWORD="yes"
+      - MYSQL_DATABASE=eventstore
+    ports:
+      - 3307:3306

docs/UPGRADE-4.0.md

@@ -172,7 +172,6 @@ final class HotelProjector
     // ...
 }
 ```
-
 If you still need the subscriber id elsewhere, read it from the metadata instead:
 
 ```php
@@ -181,7 +180,6 @@ use Patchlevel\EventSourcing\Metadata\Subscriber\AttributeSubscriberMetadataFact
 $metadata = (new AttributeSubscriberMetadataFactory())->metadata($subscriber::class);
 $subscriberId = $metadata->id;
 ```
-
 ### SubscriberAccessor and RealSubscriberAccessor
 
 The `Patchlevel\EventSourcing\Subscription\Subscriber\SubscriberAccessor` and
@@ -228,7 +226,6 @@ final class CustomResolver implements ArgumentResolver
     // ... support()
 }
 ```
-
 After:
 
 ```php
@@ -242,7 +239,6 @@ final class CustomResolver implements ArgumentResolver
     // ... support()
 }
 ```
-
 ### Custom ArgumentResolver registration
 
 Custom argument resolvers are no longer passed to the `MetadataSubscriberAccessorRepository`.
@@ -262,7 +258,6 @@ $engine = new DefaultSubscriptionEngine(
     $subscriberRepository,
 );
 ```
-
 After:
 
 ```php
@@ -277,7 +272,6 @@ $engine = new DefaultSubscriptionEngine(
     argumentResolvers: [new MyResolver()],
 );
 ```
-
 ### Batchable Subscriber
 
 The `Patchlevel\EventSourcing\Subscription\Subscriber\BatchableSubscriber` interface has been removed.
@@ -329,15 +323,13 @@ final class MigrationSubscriber implements BatchableSubscriber
     }
 }
 ```
-
 After:
 
 ```php
-use Patchlevel\EventSourcing\Attribute\BatchState;
 use Patchlevel\EventSourcing\Attribute\BatchBegin;
 use Patchlevel\EventSourcing\Attribute\BatchFlush;
 use Patchlevel\EventSourcing\Attribute\BatchRollback;
-use Patchlevel\EventSourcing\Attribute\BatchShouldFlush;
+use Patchlevel\EventSourcing\Attribute\BatchState;
 
 final class MigrationBatch
 {
@@ -355,8 +347,11 @@ final class MigrationSubscriber
     }
 
     #[Subscribe(NameChanged::class)]
-    public function handleNameChanged(NameChanged $event, #[BatchState] MigrationBatch $batch): void
-    {
+    public function handleNameChanged(
+        NameChanged $event,
+        #[BatchState]
+        MigrationBatch $batch,
+    ): void {
         $batch->nameChanged[$event->userId] = $event->name;
     }
 
@@ -372,7 +367,6 @@ final class MigrationSubscriber
     }
 }
 ```
-
 ### Parallel subscription processing
 
 The subscription engine now processes one subscription at a time instead of driving a single shared
@@ -391,7 +385,6 @@ separate `LockableSubscriptionStore` interface has been removed. Every custom st
 both:
 
 ```php
-use Closure;
 use Patchlevel\EventSourcing\Subscription\Store\SubscriptionCriteria;
 use Patchlevel\EventSourcing\Subscription\Subscription;
 
@@ -415,7 +408,6 @@ interface SubscriptionStore
     public function inLock(Closure $closure): mixed;
 }
 ```
-
 `find()` no longer locks the matched rows: it is now a plain, unlocked snapshot read. The locking
 happens per subscription inside `claim()`.
 
@@ -496,15 +488,13 @@ use Patchlevel\EventSourcing\Message\Pipe;
 
 $messages = (new Pipe($messages, $translator))->toArray();
 ```
-
 after:
 
 ```php
 use Patchlevel\EventSourcing\Message\Stream;
 
 $messages = (new Stream($messages))->transform($translator)->toList();
 ```
-
 ## Message
 
 ### AggregateHeader