Fix BC break in getSnapshotId() from named snapshots feature

Restore getSnapshotId() to its original no-parameter signature so
users who override it (as documented in the README) are not broken.
The incrementor bump is moved back to the call site via a new
resolveSnapshotId() method. Also adds README docs for named snapshots.

Fixes #237 (comment)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: freekmurze

README.md

@@ -98,16 +98,16 @@ composer require --dev spatie/phpunit-snapshot-assertions
 
 To make snapshot assertions, use the `Spatie\Snapshots\MatchesSnapshots` trait in your test case class. This adds a set of assertion methods to the class:
 
-- `assertMatchesSnapshot($actual)`
-- `assertMatchesFileHashSnapshot($actual)`
-- `assertMatchesFileSnapshot($actual)`
-- `assertMatchesHtmlSnapshot($actual)`
-- `assertMatchesJsonSnapshot($actual)`
-- `assertMatchesObjectSnapshot($actual)`
-- `assertMatchesTextSnapshot($actual)`
-- `assertMatchesXmlSnapshot($actual)`
-- `assertMatchesYamlSnapshot($actual)`
-- `assertMatchesImageSnapshot($actual)`
+- `assertMatchesSnapshot($actual, $driver, $id)`
+- `assertMatchesFileHashSnapshot($filePath, $id)`
+- `assertMatchesFileSnapshot($file, $id)`
+- `assertMatchesHtmlSnapshot($actual, $id)`
+- `assertMatchesJsonSnapshot($actual, $id)`
+- `assertMatchesObjectSnapshot($actual, $id)`
+- `assertMatchesTextSnapshot($actual, $id)`
+- `assertMatchesXmlSnapshot($actual, $id)`
+- `assertMatchesYamlSnapshot($actual, $id)`
+- `assertMatchesImageSnapshot($actual, $threshold, $includeAa, $id)`
 
 ### Snapshot Testing 101
 
@@ -202,6 +202,17 @@ $this->assertMatchesImageSnapshot($imagePath, 0.1);
 ```
 
 
+### Named Snapshots
+
+By default, snapshots are identified by an auto-incrementing number. You can pass an explicit `$id` to any assertion method to use a named snapshot instead:
+
+```php
+$this->assertMatchesJsonSnapshot($order->toJson(), 'order-json');
+$this->assertMatchesTextSnapshot($output, 'cli-output');
+```
+
+Named snapshots use a `s-` prefix internally to avoid collisions with auto-incremented ids. Named and auto-incremented snapshots can be mixed freely within a single test — named snapshots don't affect the auto-increment counter.
+
 ### Customizing Snapshot Ids and Directories
 
 Snapshot ids are generated via the `getSnapshotId` method on the `MatchesSnapshot` trait. Override the method to customize the id. By default, a snapshot id exists of the test name, the test case name and an incrementing value, e.g. `Test__my_test_case__1`.

src/Concerns/SnapshotIdAware.php

@@ -21,22 +21,11 @@ public function setUpSnapshotIncrementor()
     /*
      * Determines the snapshot's id. By default, the test case's class and
      * method names are used.
-     *
-     * If an explicit `$id` is provided, it will be prefixed with 's-' to
-     * distinguish it from auto-generated incrementor-based IDs. This avoids
-     * conflicts, should an explicit `$id` be numeric.
      */
-    protected function getSnapshotId(?string $id = null): string
+    protected function getSnapshotId(): string
     {
-        if ($id !== null) {
-            $suffix = 's-'.$id;
-        } else {
-            $this->snapshotIncrementor++;
-            $suffix = $this->snapshotIncrementor;
-        }
-
         return (new ReflectionClass($this))->getShortName().'__'.
             $this->nameWithDataSet().'__'.
-            $suffix;
+            $this->snapshotIncrementor;
     }
 }

src/MatchesSnapshots.php

@@ -4,6 +4,7 @@
 
 use PHPUnit\Framework\Attributes\PostCondition;
 use PHPUnit\Framework\ExpectationFailedException;
+use ReflectionClass;
 use ReflectionObject;
 use Spatie\Snapshots\Concerns\PhpUnitCompatibility;
 use Spatie\Snapshots\Concerns\SnapshotDirectoryAware;
@@ -161,10 +162,23 @@ protected function shouldCreateSnapshots(): bool
             && getenv('CREATE_SNAPSHOTS') !== 'false';
     }
 
+    protected function resolveSnapshotId(?string $id = null): string
+    {
+        if ($id !== null) {
+            return (new ReflectionClass($this))->getShortName().'__'.
+                $this->nameWithDataSet().'__'.
+                's-'.$id;
+        }
+
+        $this->snapshotIncrementor++;
+
+        return $this->getSnapshotId();
+    }
+
     protected function doSnapshotAssertion(mixed $actual, Driver $driver, ?string $id = null)
     {
         $snapshot = Snapshot::forTestCase(
-            $this->getSnapshotId($id),
+            $this->resolveSnapshotId($id),
             $this->getSnapshotDirectory(),
             $driver
         );
@@ -209,7 +223,7 @@ protected function doFileSnapshotAssertion(string $filePath, ?string $id = null)
 
         $fileSystem = Filesystem::inDirectory($this->getFileSnapshotDirectory());
 
-        $snapshotId = $this->getSnapshotId($id).'.'.$fileExtension;
+        $snapshotId = $this->resolveSnapshotId($id).'.'.$fileExtension;
         $snapshotId = Filename::cleanFilename($snapshotId);
 
         // If $filePath has a different file extension than the snapshot, the test should fail