php - How to implement custom item get endpoint with filtering in api platform?

Solution:

It's definitely possible, but depending on your choice there's more work you need to do to get the desired result.

I'll go with custom operation since that's easier to explain and I already have some code examples.

To get the information you need for filtering you'll need to go with a lower level approach. The key part that you missed, is that API Platform is built on top of Symfony, so you can just use theRequest (for a custom operation) or theRequestStack (for a data provider) to get the filters.

Also to make sure API Platform knows how to serialize the data you are outputting (Statistics object), you'll need to use a DTO.

Here's how the code would look like:

On your entity, we add the custom operation class and specify the output as the Statistics class:

 * @ApiResource(
 *    ...
 *     itemOperations={
 *          "get_statistics"={
 *              "method"="GET",
 *              "path"="/users/{id}/statistics",
 *              "controller"=UserStatsAction::class,
 *              "input"=Statistics::class
 *          }
 *     },
 *    ...
 */
Copy code

The custom operation code sample:

final class UserStatsAction
{
    private $em;


    public function __construct(EntityManagerInterface $em)
    {
        $this->em = $em;
    }

    public function __invoke(Request $request)
    {
        $id = $request->get('id');
        $repository = $this->em->getRepository(User::class);
        if(!($user = $repository->find($id))) {
            throw new NotFoundHttpException();
        }

        $sports = $request->query->get('sport', []);
        $outcome = $request->query->get('outcome');

        // Optional: validate your filter data
        $validator = Validation::createValidator();
        $context = $validator->startContext();
        $context->atPath('sports')->validate($sports, [
            new Assert\Choice([
                'choices' => ['football', 'basketball'],
            ]),
        ]);
        $context->atPath('outcome')->validate($outcome, [
            new Assert\Choice([
                'choices' => ['win', 'loose', 'tie'],
            ]),
        ]);
        $violations = $context->getViolations();

        if (0 !== count($violations)) {
            throw new ValidationException($violations);
        }

        // I'll assume you are hnadiling empty/nulls value properly inside this method
        // and return all the stats if 
        $results = $repository->getStatistics($sports, $outcome);

        // For this to work, you'll need to set a DTO for your stats
        return $results;
    }
}
Copy code

I'm using theRequest as argument for custom operation, not theUser entity. There is some code in my example that you might not need, like fetching the user from the repository or validating the filters (I do encourage user input cleanup/validation though).

One important mention: custom operations are discouraged by API Platform, and you'll lose GraphQL support. If you need GraphQL, the same result can be accomplished with aDataProvider but that's a more advanced setup and I'll need to mock some parts of your app to figure it out.

Hope this helps.

Update:

For filters to work you'll need to also update the OpenAPI/Swagger configuration, as tobias ingold pointed out in the comment below.

You can do that using PHP and creating a Normalizer, as described in the Override the OpenAPI speficiation section of the docs.

This can also be done by expanding on theAPIResource annotation, here's an example:

 * @ApiResource(
 *     ...
 *     collectionOperations={
 *          "post",
 *          "get"={
 *              "openapi_context"={
 *                  "parameters"={
 *                      {
 *                          "name": "<query_string_param_name>",
 *                          "type": "string",
 *                          "in": "query",
 *                          "required": false,
 *                          "description": "description",
 *                          "example": ""
 *                      }
 *                  }
 *              }
 *          }
 *     }
 *     ...
 *  })
Copy code

I found this approach easier to use, but it's not documented. I extrapolated this based on my OpenAPI spec knowledge and the Configuring the Entity Receiving the Uploaded File example in the official documentation.