[RFC] Resources defined outside of PHP code (runtime / external metadata sources)

Start by reading AbstractItemNormalizer, IriConverter, ResourceClassResolver, and the cached metadata factory implementations named in the issue. The proposal has unresolved design questions about resource identity, instantiation, and cache invalidation, so first agree on the direction with maintainers. Done means implementing the agreed runtime resource support and covering resource discovery, serialization, instantiation, and IRI behavior with tests.

Summary

Allow API resources declared from a source other than PHP code (a database, another API, a configuration
service) to work without a PHP class per resource. Discovery and metadata can already be provided by
decorating the metadata factories; what is missing are a few runtime hooks, because the serializer, the IRI
converter and the resource class resolver derive the resource from $object::class.

Use case

Administrators define content models at runtime (fields, types, relations) without deployment or migration.
We want each model to be a real API resource:

• GET /dynamic/faq/{id} → "@type": "DynamicFaq", properties question, answer, theme…
• per-model JSON Schema / OpenAPI / Hydra documentation
• per-model validation derived from field definitions
• IRIs generated and resolved like any other resource (getIriFromResource, getResourceFromIri)
• a new or modified model available without a deployment

How the data is persisted is up to the application (in our case a generic Doctrine entity with a JSON
column), exactly as with DTOs and stateOptions today.

Similar needs: headless CMS builders, form builders, multi-tenant schemas, schemaless document stores,
resources proxied from a remote API whose schema is discovered at runtime.

What already works

Decorating ResourceNameCollectionFactoryInterface, ResourceMetadataCollectionFactoryInterface (below the
cache) and the property factories lets an application declare resources, operations and properties from any
source. The Laravel Eloquent integration does it for properties. Types come from ApiProperty::nativeType /
schema, so no reflection is needed. Operations, routes and documentation can be generated this way,
provided a few metadata factories stop assuming the resource is a class (see below): with the resource
metadata declared at the innermost level (so that the core factories still apply their defaults), route
loading currently fails with ReflectionException: Class "DynamicFaq" does not exist.

What breaks

Once a resource is identified by a name that is not a class (DynamicFaq):

Where	Code	Effect
ParameterResourceMetadataCollectionFactory::createParametersFromAttributes()	new \ReflectionClass($resourceClass)	ReflectionException while loading routes
FiltersResourceMetadataCollectionFactory	new \ReflectionClass($resourceClass)	ResourceClassNotFoundException
Doctrine ORM/ODM metadata factories (resource collection, parameters, links, properties, discriminator)	ManagerRegistry::getManagerForClass()	ReflectionException from Doctrine on an unknown class
AbstractItemNormalizer::instantiateObject()	new \ReflectionClass($class)	ReflectionException on every write operation
AbstractItemNormalizer::normalize()	$context['force_resource_class'] ?? $this->getObjectClass($data)	resource derived from the PHP class of the object
IriConverter::getIriFromResource()	same	wrong or missing IRI for nested relations, cache purge, Mercure
ResourceClassResolver::getResourceClass() / isResourceClass()	getObjectClass() + is_a()	an object cannot belong to a resource that is not a class
CachedResourceNameCollectionFactory, Cached*MetadataFactory	no invalidation	a new resource is only visible after a cache clear

Workarounds without core changes:

1. Generate one PHP class per resource at runtime: code generation in production, opcache/container
   rebuilds, multi-server synchronisation.
2. Map all resources onto one shared class: getObjectClass() always returns that class, so the resource
   of a nested object cannot be determined.
3. Decorate the normalizers, IriConverter and ResourceClassResolver: re-implementing part of the core
   outside the project, fragile across upgrades.

Proposal

1. Objects carrying their resource

interface ResourceAwareInterface
{
    public function getResource(): string;
}

When an object implements it, AbstractItemNormalizer, IriConverter and ResourceClassResolver use
getResource() instead of $object::class. Nested relations and getIriFromResource() outside the
operation context then work as for any resource.

Optionally, the core could ship a generic implementation for applications that do not want their own:

final class DynamicResource implements ResourceAwareInterface, \ArrayAccess, \IteratorAggregate
{
    public function __construct(private readonly string $resource, private array $data = []) {}

    public function getResource(): string { return $this->resource; }
}

2. Instantiation hook for name-identified resources

When the resource is not a class, the serializer delegates instantiation (and property read/write) instead
of calling new \ReflectionClass(): by default to DynamicResource, or to a class declared in the
resource metadata. The processor receives that object and maps it to the domain model, as DTOs with
stateOptions do today.

3. Metadata cache invalidation (optional)

Cache tags on the metadata pools + MetadataCacheInvalidatorInterface::invalidate(string $resource), so a
resource added or modified at runtime is picked up without a cache clear. Routing can rely on a catch-all
route or a router cache fingerprint, left to the application at first. GraphQL is out of scope.

Backward compatibility

No BC break: everything is opt-in and introduced through new interfaces and classes. Existing interfaces are
not modified, and objects that do not implement ResourceAwareInterface behave exactly as today. It can ship
in a 5.x minor, flagged experimental.

Known limitation: many extension points document string $resourceClass as class-string. Third-party code
assuming so (new \ReflectionClass($resourceClass), class_exists(), getRepository()) keeps working for
class-based resources but will not support name-identified resources. This should be documented for
extension authors.

Open questions

1. Is a resource identity that is not a class name acceptable for the project?
2. ResourceAwareInterface only, or also a generic DynamicResource shipped by the core?
3. Resource name vs. shortName: reuse shortName as identity, or introduce a new key?
4. Is metadata cache invalidation in scope, or left to applications?

Contribution

We can implement the ResourceAwareInterface support first, then the instantiation hook, after agreement on
the direction. We can also contribute documentation on providing resources by decorating the metadata
factories.