feat(laravel): boot without a database via dumped metadata

[soyuka]

Problem

To expose an Eloquent model, API Platform reads its metadata (columns, types, relations) from the live database schema (ModelMetadata::getAttributes() → getColumns()/getIndexes()). That introspection runs while the ResourceMetadataCollection is built, and that build happens at boot: src/Laravel/routes/api.php iterates every resource to register routes.

So the app cannot boot when no migrated database is reachable. This breaks common cacheless boots:

• docker build (DB service not running);
• composer install → @php artisan package:discover;
• static analysis (Larastan/PHPStan) in CI, which boots the app.

The existing metadata cache only short-circuits the DB read if it was already warmed — and warming needs a boot with the DB up; the configured store may also be redis/memcached (unavailable at build, not committable).

Refs #8131.

Solution

Pre-compute the schema metadata once, with the DB up, dump it to a single file that can be committed to git or baked into a Docker image, and seed it back at boot — bypassing the DB.

• api-platform:metadata:dump {--path=} — resolves the path from --path or the api-platform.metadata_dump config, iterates ResourceNameCollectionFactoryInterface, and writes the per-model attribute and relation arrays (ModelMetadata::getAttributes() / getRelations() — the step that hits the DB, run it with the DB up). Written via a temporary file + atomic rename().
• ModelMetadata seeding — its constructor gains optional attributes/relations arguments that seed its existing per-class caches. At boot, when api-platform.metadata_dump points at an existing file and APP_DEBUG is false, the container builds ModelMetadata pre-seeded from the dump. Skipped when APP_DEBUG is true so local dev always introspects fresh.
• Config — api-platform.metadata_dump defaults to null (feature disabled); the user explicitly chooses a VCS/image-committable path.

Why cache ModelMetadata rather than the resource collection

ModelMetadata::getAttributes() is the only boot-time component that touches the database; the whole property/metadata-build chain (EloquentPropertyNameCollectionMetadataFactory, EloquentPropertyMetadataFactory, RelationMetadataLoader, EloquentExtractor, ParameterResourceMetadataCollectionFactory) reaches the DB only through it. Caching that one layer lets the entire resource-metadata chain boot offline while every factory stays live.

Because the dump then holds only plain attribute/relation arrays (scalars and class-strings):

• it is read back with unserialize(..., ['allowed_classes' => false]) — no object-injection surface;
• it can never contain a Closure, so a closure provider/processor on a resource cannot break serialize();
• the dump command receives a live (unseeded) ModelMetadata via a contextual binding, so it never reads back its own dump.

The resource-metadata factory chain is left completely untouched (no container-binding rename, no decorator).

Usage

// config/api-platform.php
'metadata_dump' => storage_path('app/api-platform/metadata.dump'),

php artisan api-platform:metadata:dump   # run with the DB up, commit/bake the file

Re-run the command whenever your models change.

Tests

New tests, runnable without a database:

• Tests/Console/DumpMetadataCommandTest.php — dumps the attribute/relation map; no-path failure; non-Model resources skipped.
• Tests/Metadata/DumpedMetadataBootTest.php — a seeded ModelMetadata serves dumped data without DB introspection; bypassed when app.debug=true.
• Tests/Unit/Metadata/ModelMetadataTest.php — the seeding contract.

cd src/Laravel && vendor/bin/phpunit --filter 'DumpMetadataCommandTest|DumpedMetadataBootTest|ModelMetadataTest'
→ OK (12 tests, 26 assertions)