Bug: explicit `class` parameter in `#[AsResource]` is always overwritten by the resource PHP class

[nfacciolo]

Description

When using #[AsResource(class: SomeEntity::class)] to explicitly set the entity class on a Resource DTO, the class parameter is silently ignored. ResourceMetadata::getClass() always returns the Resource PHP class itself (e.g. FruitResource) instead of the explicitly configured entity class (e.g. Fruit).

Steps to reproduce

#[AsResource(
    alias: 'app.fruit',
    class: Fruit::class,
    driver: false,
)]
final class FruitResource implements ResourceInterface {}

$collection = $factory->create(FruitResource::class);
$metadata->getClass(); // Expected: Fruit — Actual: FruitResource

Root cause

OperationDefaultsTrait::getResourceWithDefaults() unconditionally overwrites the class property with $resourceClass, ignoring the value from #[AsResource(class:)]:

 // line 34 — always overwrites
 $resource = $resource->withClass($resourceClass);

This is inconsistent with every other property in the same method, all of which use null-checks before applying defaults (alias, applicationName, name).

Proposed fix

- $resource = $resource->withClass($resourceClass);
+ if (null === $resource->getClass()) {
+     $resource = $resource->withClass($resourceClass);
+ }

Versions

Reproduced on v1.14.0 and branch 1.15.

[loic425]

Yes, @stlgaits warned me about this issue.
The first idea I have is to deprecate the class attribute from the AsResource PHP attribute, Cause it doesn't work like this.
It's only required when using an external configuration file:

declare(strict_types=1);

use App\Entity\Book;
use Sylius\Resource\Metadata\Index;
use Sylius\Resource\Metadata\Operations;
use Sylius\Resource\Metadata\ResourceMetadata;

return (new ResourceMetadata())
    ->withClass(Book::class)
    ->withOperations(
        new Operations([
            new Index(),
        ])
    )
;

For now there's no auto-mapper usage such as the APIP one with:

stateOptions: new Options(entityClass: BookEntity::class),

[nfacciolo]

Thank you for the clarification.

I was wondering whether fixing the bug might be preferable to deprecating the class attribute.

A common pattern is to decouple the resource (DTO/API layer) from the Doctrine entity:

#[AsResource(class: Fruit::class)]
class FruitResource
{
    public ?int $id = null;
    public string $name = '';
}

In this setup, the resource represents the exposed model, while the entity remains focused on persistence. Without a working class attribute, both concerns would need to be merged.

From what I can see, the current behavior seems to come from class being applied unconditionally in OperationDefaultsTrait::getResourceWithDefaults(), whereas the other properties are only set when null. Adding a similar null-check might resolve the issue while keeping the attribute available.

[loic425]

Did you have a look at the DDD guide? It does not need to set this class. But it requires custom providers & processors. That's why that's be cool to implement the stateOptions from APIP (I started the feature). and yes you can already use a DTO.

[nfacciolo]

Yes, I did. I initially found the approach very interesting.

However, when applying it across a full project, it tends to require quite a few additional classes (custom providers, processors, etc.), and the overall customization flow doesn’t always feel very intuitive.

That’s partly why I started thinking about a grid component approach — something that might offer more flexibility with less structural overhead, and this discussion came up in that context.

Of course, I may be missing something in the intended usage, so I’m open to feedback.