feat(laravel): detect stale metadata dump via fingerprints

The dumped metadata is a frozen snapshot served outermost (above the
cache) when APP_DEBUG is false, so a changed resource or migrated
schema is served stale with no signal. Detect both drift axes,
warn-only, without breaking the no-database boot the dump provides:

- resource drift: hash the ApiResource source files (content, not
  mtime, so committed/baked dumps survive git clone and docker build)
  and warn at boot when they differ from the dumped fingerprint;
- schema drift: hash the live Eloquent schema and warn on
  MigrationsEnded when it differs (DB only reachable then).

The dump file gains a versioned envelope carrying both fingerprints;
bare-map dumps from the previous format still load without a warning.

The dump command no longer unwraps the resolved factory at runtime to
reach the live source: the source metadata chain is bound under its own
container key, the interface everyone injects resolves to the dumped
wrapper, and the command receives the source chain via a contextual
binding. Removes the DumpedResourceCollectionMetadataFactory::getDecorated()
seam and guarantees the command cannot read back its own dump.

Refs #8131, #8290

Author: soyuka

src/Laravel/ApiPlatformDeferredProvider.php

@@ -214,7 +214,7 @@ public function register(): void
 
         $this->autoconfigure($classes, ProviderInterface::class, $providers);
 
-        $this->app->singleton(ResourceMetadataCollectionFactoryInterface::class, function (Application $app) {
+        $this->app->singleton('api_platform.metadata.resource_collection_factory.source', function (Application $app) {
             /** @var ConfigRepository $config */
             $config = $app['config'];
             $formats = $config->get('api-platform.formats');
@@ -391,7 +391,7 @@ public function provides(): array
             ParameterProvider::class,
             FilterQueryExtension::class,
             'filters',
-            ResourceMetadataCollectionFactoryInterface::class,
+            'api_platform.metadata.resource_collection_factory.source',
             'api_platform.graphql.state_provider.parameter',
             FieldsBuilderEnumInterface::class,
             ExceptionHandlerInterface::class,

src/Laravel/ApiPlatformProvider.php

@@ -99,6 +99,7 @@
 use ApiPlatform\Laravel\Metadata\CachePropertyMetadataFactory;
 use ApiPlatform\Laravel\Metadata\CachePropertyNameCollectionMetadataFactory;
 use ApiPlatform\Laravel\Metadata\DumpedResourceCollectionMetadataFactory;
+use ApiPlatform\Laravel\Metadata\MetadataDumpFingerprint;
 use ApiPlatform\Laravel\Routing\IriConverter;
 use ApiPlatform\Laravel\Routing\Router as UrlGeneratorRouter;
 use ApiPlatform\Laravel\Routing\SkolemIriConverter;
@@ -175,6 +176,7 @@
 use Http\Discovery\Psr17Factory;
 use Illuminate\Config\Repository as ConfigRepository;
 use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Database\Events\MigrationsEnded;
 use Illuminate\Foundation\Http\Events\RequestHandled;
 use Illuminate\Routing\Router;
 use Illuminate\Support\Facades\Event;
@@ -390,7 +392,7 @@ public function register(): void
 
         // ObjectMapper metadata factory support
         if (interface_exists(ObjectMapperInterface::class)) {
-            $this->app->extend(ResourceMetadataCollectionFactoryInterface::class, static function (ResourceMetadataCollectionFactoryInterface $inner, Application $app) {
+            $this->app->extend('api_platform.metadata.resource_collection_factory.source', static function (ResourceMetadataCollectionFactoryInterface $inner, Application $app) {
                 return new ObjectMapperMetadataCollectionFactory(
                     $inner,
                     $app->make(ObjectMapperMetadataFactoryInterface::class)
@@ -399,24 +401,31 @@ public function register(): void
         }
 
         // Parameter metadata factory with Laravel Eloquent support
-        $this->app->extend(ResourceMetadataCollectionFactoryInterface::class, static function (ResourceMetadataCollectionFactoryInterface $inner, Application $app) {
+        $this->app->extend('api_platform.metadata.resource_collection_factory.source', static function (ResourceMetadataCollectionFactoryInterface $inner, Application $app) {
             return new Metadata\Resource\Factory\ParameterResourceMetadataCollectionFactory($inner, $app->make(ModelMetadata::class), new \Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter());
         });
 
-        // Outermost: serve the resource metadata from a dumped file so the app can boot without a
-        // live database. Skipped when APP_DEBUG is true so local development always recomputes fresh
-        // metadata (mirroring the 'array' cache choice).
-        $this->app->extend(ResourceMetadataCollectionFactoryInterface::class, static function (ResourceMetadataCollectionFactoryInterface $inner, Application $app) {
+        // The metadata factory everyone injects: serve the resource metadata from a dumped file so the
+        // app can boot without a live database. Skipped when APP_DEBUG is true so local development
+        // always recomputes fresh metadata (mirroring the 'array' cache choice). The dump command gets
+        // the source factory directly (contextual binding below) so it never reads back its own dump.
+        $this->app->singleton(ResourceMetadataCollectionFactoryInterface::class, static function (Application $app) {
             /** @var ConfigRepository $config */
             $config = $app['config'];
 
+            $source = $app->make('api_platform.metadata.resource_collection_factory.source');
+
             if (true === $config->get('app.debug')) {
-                return $inner;
+                return $source;
             }
 
-            return new DumpedResourceCollectionMetadataFactory($inner, $config->get('api-platform.metadata_dump'));
+            return new DumpedResourceCollectionMetadataFactory($source, $config->get('api-platform.metadata_dump'), $app->make(LoggerInterface::class), $config->get('api-platform.resources') ?? []);
         });
 
+        $this->app->when(Console\DumpMetadataCommand::class)
+            ->needs(ResourceMetadataCollectionFactoryInterface::class)
+            ->give(static fn (Application $app) => $app->make('api_platform.metadata.resource_collection_factory.source'));
+
         $this->app->singleton(OperationMetadataFactory::class, static function (Application $app) {
             return new OperationMetadataFactory($app->make(ResourceNameCollectionFactoryInterface::class), $app->make(ResourceMetadataCollectionFactoryInterface::class));
         });
@@ -1498,6 +1507,41 @@ public function boot(): void
             $this->app->make(SkolemIriConverter::class)->reset();
         });
 
+        // The schema can only be fingerprinted while the database is reachable, so detect schema
+        // drift against the dump right after a migration runs (warn-only — the dump is not rewritten).
+        $dumpPath = $config->get('api-platform.metadata_dump');
+        if (\is_string($dumpPath) && '' !== $dumpPath && true !== $config->get('app.debug')) {
+            Event::listen(MigrationsEnded::class, function () use ($dumpPath): void {
+                $this->warnIfDumpedSchemaIsStale($dumpPath);
+            });
+        }
+
         $this->loadRoutesFrom(__DIR__.'/routes/api.php');
     }
+
+    private function warnIfDumpedSchemaIsStale(string $dumpPath): void
+    {
+        if (!is_file($dumpPath)) {
+            return;
+        }
+
+        $contents = file_get_contents($dumpPath);
+        if (false === $contents) {
+            return;
+        }
+
+        $data = unserialize($contents, ['allowed_classes' => true]);
+        if (!\is_array($data) || !\is_string($data['schema_fingerprint'] ?? null)) {
+            return;
+        }
+
+        $resourceClasses = $this->app->make(ResourceNameCollectionFactoryInterface::class)->create();
+        $current = MetadataDumpFingerprint::schema($resourceClasses, $this->app->make(ModelMetadata::class));
+
+        if ($current === $data['schema_fingerprint']) {
+            return;
+        }
+
+        $this->app->make(LoggerInterface::class)->warning('The API Platform metadata dump at "{path}" is stale: the database schema changed after migration. Run "php artisan api-platform:metadata:dump" to refresh it.', ['path' => $dumpPath]);
+    }
 }

src/Laravel/Console/DumpMetadataCommand.php

@@ -13,7 +13,8 @@
 
 namespace ApiPlatform\Laravel\Console;
 
-use ApiPlatform\Laravel\Metadata\DumpedResourceCollectionMetadataFactory;
+use ApiPlatform\Laravel\Eloquent\Metadata\ModelMetadata;
+use ApiPlatform\Laravel\Metadata\MetadataDumpFingerprint;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceNameCollectionFactoryInterface;
 use Illuminate\Console\Command;
@@ -35,6 +36,7 @@ final class DumpMetadataCommand extends Command
     public function __construct(
         private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory,
         private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory,
+        private readonly ModelMetadata $modelMetadata,
     ) {
         parent::__construct();
     }
@@ -49,25 +51,31 @@ public function handle(): int
             return self::FAILURE;
         }
 
-        // Always rebuild from the live source, never from a previously dumped (possibly stale) file.
-        $factory = $this->resourceMetadataCollectionFactory;
-        while ($factory instanceof DumpedResourceCollectionMetadataFactory) {
-            $factory = $factory->getDecorated();
-        }
-
+        // The container hands this command the source factory (never the dumped layer), so building
+        // always reads the live source rather than a previously dumped (possibly stale) file.
         $metadata = [];
         foreach ($this->resourceNameCollectionFactory->create() as $resourceClass) {
-            $metadata[$resourceClass] = $factory->create($resourceClass);
+            $metadata[$resourceClass] = $this->resourceMetadataCollectionFactory->create($resourceClass);
         }
 
+        // Fingerprints let the app detect a stale dump later: resources at boot (no DB),
+        // schema after a migration (DB up). Computed here while the live source is available.
+        $resourcePaths = config('api-platform.resources') ?? [];
+        $envelope = [
+            'version' => MetadataDumpFingerprint::VERSION,
+            'resources_fingerprint' => MetadataDumpFingerprint::resources($resourcePaths),
+            'schema_fingerprint' => MetadataDumpFingerprint::schema(array_keys($metadata), $this->modelMetadata),
+            'metadata' => $metadata,
+        ];
+
         $directory = \dirname($path);
         if (!is_dir($directory) && !mkdir($directory, 0o755, true) && !is_dir($directory)) {
             $this->error(\sprintf('Unable to create directory "%s".', $directory));
 
             return self::FAILURE;
         }
 
-        if (false === file_put_contents($path, serialize($metadata))) {
+        if (false === file_put_contents($path, serialize($envelope))) {
             $this->error(\sprintf('Unable to write the metadata dump to "%s".', $path));
 
             return self::FAILURE;

src/Laravel/Metadata/DumpedResourceCollectionMetadataFactory.php

@@ -15,11 +15,17 @@
 
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use Psr\Log\LoggerInterface;
 
 /**
  * Serves the resource metadata from a file dumped by api-platform:metadata:dump, bypassing the
  * database introspection that happens while building the collection. Delegates to the decorated
  * factory for any resource missing from the dump (or when no dump file exists).
+ *
+ * When the dump carries a resources fingerprint, it is checked against the current source files
+ * once on load: a mismatch logs a warning (the dump is still served, so the no-database boot keeps
+ * working) telling the operator to re-run api-platform:metadata:dump. Database schema drift cannot
+ * be detected here without a connection; it is reported by the migrate listener instead.
  */
 final class DumpedResourceCollectionMetadataFactory implements ResourceMetadataCollectionFactoryInterface
 {
@@ -28,9 +34,14 @@ final class DumpedResourceCollectionMetadataFactory implements ResourceMetadataC
      */
     private ?array $dumped = null;
 
+    /**
+     * @param list<string> $resourcePaths
+     */
     public function __construct(
         private readonly ResourceMetadataCollectionFactoryInterface $decorated,
         private readonly ?string $dumpPath,
+        private readonly ?LoggerInterface $logger = null,
+        private readonly array $resourcePaths = [],
     ) {
     }
 
@@ -41,15 +52,6 @@ public function create(string $resourceClass): ResourceMetadataCollection
         return $dumped[$resourceClass] ?? $this->decorated->create($resourceClass);
     }
 
-    /**
-     * Exposes the decorated factory so the dump command can rebuild metadata from the live source
-     * instead of reading back a previously dumped (possibly stale) file.
-     */
-    public function getDecorated(): ResourceMetadataCollectionFactoryInterface
-    {
-        return $this->decorated;
-    }
-
     /**
      * @return array<class-string, ResourceMetadataCollection>
      */
@@ -69,7 +71,31 @@ private function load(): array
         }
 
         $data = unserialize($contents, ['allowed_classes' => true]);
+        if (!\is_array($data)) {
+            return $this->dumped = [];
+        }
+
+        // An envelope (version >= 1) carries fingerprints; a bare map is an older dump with no
+        // freshness information — serve it as-is without a staleness check.
+        if (!isset($data['version'], $data['metadata']) || !\is_array($data['metadata'])) {
+            return $this->dumped = $data;
+        }
+
+        $this->warnIfResourcesChanged(\is_string($data['resources_fingerprint'] ?? null) ? $data['resources_fingerprint'] : null);
+
+        return $this->dumped = $data['metadata'];
+    }
+
+    private function warnIfResourcesChanged(?string $dumpedFingerprint): void
+    {
+        if (null === $dumpedFingerprint || null === $this->logger || [] === $this->resourcePaths) {
+            return;
+        }
+
+        if (MetadataDumpFingerprint::resources($this->resourcePaths) === $dumpedFingerprint) {
+            return;
+        }
 
-        return $this->dumped = \is_array($data) ? $data : [];
+        $this->logger->warning('The API Platform metadata dump at "{path}" is stale: resource files changed since it was generated. Run "php artisan api-platform:metadata:dump" to refresh it.', ['path' => $this->dumpPath]);
     }
 }

src/Laravel/Metadata/MetadataDumpFingerprint.php

@@ -0,0 +1,99 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Laravel\Metadata;
+
+use ApiPlatform\Laravel\Eloquent\Metadata\ModelMetadata;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Computes freshness fingerprints for the metadata dump written by api-platform:metadata:dump.
+ *
+ * Two independent axes, because the dump exists to let the app boot without a database:
+ *  - resources(): hashes the ApiResource source files, so it can run at boot with no DB;
+ *  - schema(): hashes the live Eloquent schema, so it can only run when a DB is reachable.
+ */
+final class MetadataDumpFingerprint
+{
+    public const VERSION = 1;
+
+    /**
+     * Content hash of every PHP file under the given resource paths.
+     *
+     * Content-based (not filemtime) on purpose: a committed or image-baked dump must stay valid
+     * across `git clone` and `docker build`, neither of which preserves modification times.
+     *
+     * @param list<string> $paths
+     */
+    public static function resources(array $paths): string
+    {
+        $hashes = [];
+        foreach ($paths as $path) {
+            if (is_file($path)) {
+                $hashes[$path] = sha1_file($path) ?: '';
+                continue;
+            }
+
+            if (!is_dir($path)) {
+                continue;
+            }
+
+            $iterator = new \RecursiveIteratorIterator(
+                new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS),
+            );
+            foreach ($iterator as $file) {
+                if (!$file instanceof \SplFileInfo || 'php' !== $file->getExtension()) {
+                    continue;
+                }
+
+                $pathname = $file->getPathname();
+                $hashes[$pathname] = sha1_file($pathname) ?: '';
+            }
+        }
+
+        ksort($hashes);
+
+        return hash('xxh128', serialize($hashes));
+    }
+
+    /**
+     * Hash of the live Eloquent schema (columns + relations) for every model-backed resource.
+     * Requires a database connection.
+     *
+     * @param iterable<class-string> $resourceClasses
+     */
+    public static function schema(iterable $resourceClasses, ModelMetadata $modelMetadata): string
+    {
+        $signature = [];
+        foreach ($resourceClasses as $resourceClass) {
+            try {
+                $model = (new \ReflectionClass($resourceClass))->newInstanceWithoutConstructor();
+            } catch (\ReflectionException) {
+                continue;
+            }
+
+            if (!$model instanceof Model) {
+                continue;
+            }
+
+            $signature[$resourceClass] = [
+                'attributes' => $modelMetadata->getAttributes($model),
+                'relations' => $modelMetadata->getRelations($model),
+            ];
+        }
+
+        ksort($signature);
+
+        return hash('xxh128', serialize($signature));
+    }
+}