RFC: A "Expression" Action for RAD

[Richard87]

Description
In this example we wouldnt need a basic class to get the item object, the input dto, and call the function, we could define it directly :)

Cons:

• No autocomplet/typehints in the expression
• a litte more complex API-Platform
• A new distinction, item for the API Resource, and input for the DTO

Pros:

• Slightly improved DX
• Rapid application development improvements

Example
An Action could look like this:

new Action(
    input: CreateAreaDto::class,
    expression: 'item.createArea(input.county)',
    uriTemplate: '/partnerships/{id}/create_area',
    security: "is_granted('ROLE_ADMIN')",
),

A proof of concept look like this:

<?php

namespace App\Service\ApiPlatform;

use ApiPlatform\Metadata\HttpOperation;
use App\Controller\ActionController;

#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
class Action extends HttpOperation
{
    private string $expression;

    public function __construct(
        string $name,
        string $input,
        string|false|null $output,
        string $expression,
        string $uriTemplate,
        string|array|null $uriVariables,
        string $security,
        string|null $securityPostDenormalize,
    ) {
        parent::__construct(
            method: 'POST',
            uriTemplate: $uriTemplate,
            uriVariables: $uriVariables,
            controller: ActionController::class,
            security: $security,
            securityPostDenormalize: $securityPostDenormalize,
            input: $input,
            output: $output,
            name: $name
        );

        $this->expression = $expression;
    }

    public function getExpression(): string
    {
        return $this->expression;
    }
}

And the controller:

<?php

namespace App\Controller;

use ApiPlatform\State\CallableProvider;
use App\Service\ApiPlatform\Action;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
use Symfony\Component\HttpFoundation\Request;

class ActionController
{
    private CallableProvider $provider;

    public function __construct(
        #[AutoWire(service: 'api_platform.state_provider')] CallableProvider $provider,
        private EntityManagerInterface $em,
    ) {
        $this->provider = $provider;
    }

    public function __invoke(Request $request, $data)
    {
        $attributes = $request->attributes;
        /** @var Action $operation */
        $operation = $attributes->get('_api_operation');
        $className = $attributes->get('_api_resource_class');
        $id = $attributes->get('id');


        if (!$id || !$className || !$operation) {
            throw new \RuntimeException('Invalid action, missing operation, className or id');
        }

        $repo = $this->em->getRepository($className);
        $object = $repo->find($id);
        $expressionLanguage = new ExpressionLanguage();

        return $expressionLanguage->evaluate($operation->getExpression(), ['item' => $object, 'input' => $data]);
    }
}

The current approach have a few limitations:

• I struggled to create optional arguments for the action (some strange error :O ) so currently all specified are required
• Requires id the the uriTemplate, no support for other types of identifiers (hardcoded)

I really like the separation of item and input, the current solution with object, data and previous_data is confusing when you need to deal with it...

I would love to solve these issues with tighter integration in API-Platform Core :)

[soyuka]

provider is already a callable you don't need to (and shouldn't) use a controller imo.

Always prefer declaring your resource on the DTO itself.

[Richard87]

Hmm, Interresting point, Provider is to return objects, for Action operation (not REST), I have always gone for the controller option.

Even if ´provider` is used, can it be used to call a method on the resource?

This does not work unfortunetley (tested on PHP 8.1) :)

controller: fn(Partnership $p, AddAreaDto $dto) => $p->addArea($dto->area),

That would be amazing :D

Edit:

First version of this concept used provider, but provider is nessesary to retrieve the object, I think controller is the most correct right now, but it's not allowed to create anonumous function

[soyuka]

it needs to implement the interface, look

core/tests/Fixtures/TestBundle/Entity/RelationGroupImpactOnCollection.php

Line 24 in 40b637f

provider: [RelationGroupImpactOnCollection::class, 'getData'],

[Richard87]

Thats an interresting idea, but you would not get access to the stored item (previous_data) or the input object (data)

[soyuka]

yes you do via the $context

[Richard87]

Hmmm, I don't see how you could get the input object and the item object with this style:

new Post(
    uriTemplate: '/partnerships/{id}/add_area',
    input: AddAreaDto::class,
    name: 'addPartnershipArea',
    provider: [Partnership::class, 'createArea2'],
),

I get the ID and the data type etc, but no objects. Since this is a method on the resource/entity, I don't have any services available.

In my case, I might also need the provider to fetch the object from the database, so using controller makes much more sense.

Basically, I would love to deprecate data and previous_data, and replace them with item and input. That would make it way easier to reason about (in my opinion!).

An expression action would simplify a lot of operations, but I'm not sure how "deep" the integration must go, or how it would impact other interfaces, like GraphQL...

Ofcourse, leveraging controller and Symfony's Value Resolver, it's not a crazy amount of extra code to deal with on my own, so feel free to close the issue if its not worth it for API-Platform (Risk vs Reward vs Maintenance) 👍

class AddArea
{
    public function __invoke(AddAreaDto $area, Partnership $partnership): Partnership {
        return $partnership->createArea($area->county);
    }
}

[soyuka]

No problem I think the discussion is important nonetheless.

I get the ID and the data type etc, but no objects. Since this is a method on the resource/entity, I don't have any services available.

I think that this is the main issue, declare the Resource on the Input and use your entityClass as a resource parameter, see #5275 which would probably help using our Doctrine providers.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.