Flag of Ukraine
SymfonyCasts stands united with the people of Ukraine
TRACK

Symfony 5 >

COURSE

API Platform Part 3: Custom Resources

Buy Access to Course

Custom Filter for Custom Resources

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00
Previous Chapter

Next Chapter
Edit on GitHub

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Let's create one more custom filter: this time for DailyStats. Here's our mission: to be able to add a ?from= date on the URL. For example, if we go to /api/daily-stats.jsonld, we see all the stats. But if we add ?from=2020-09-01, we want to only show stats on that day or later.

Let's do this! Start basically the same way as before: in the src/ApiPlatform/ directory, create a new PHP class called DailyStatsDateFilter:

18 lines src/ApiPlatform/DailyStatsDateFilter.php
... lines 1 - 2
namespace App\ApiPlatform;
... lines 4 - 7
class DailyStatsDateFilter implements FilterInterface
{
... lines 10 - 16
}

Creating the Filter Class

For the search filter, we extended AbstractFilter:

38 lines src/ApiPlatform/CheeseSearchFilter.php
... lines 1 - 4
use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter;
... lines 6 - 8
class CheeseSearchFilter extends AbstractFilter
{
... lines 11 - 36
}

but that class only works for entity resources. This time, implement FilterInterface. Now, be careful. There are multiple FilterInterface in API platform. One is for the ORM, and even inside the main part of API Platform, there are 2: one in Serializer and one in Api. Get the one in Serializer:

18 lines src/ApiPlatform/DailyStatsDateFilter.php
... lines 1 - 4
use ApiPlatform\Core\Serializer\Filter\FilterInterface;
... lines 6 - 7
class DailyStatsDateFilter implements FilterInterface
{
... lines 10 - 16
}

This FilterInterface actually extends the other one from Api\ but it has extra integration that will make our life much easier.

Back in the new class, go to "Code"->"Generate" - or Command + N on a Mac - and hit "Implement Methods" to add the two we need... which are quite similar to the two methods we had before:

18 lines src/ApiPlatform/DailyStatsDateFilter.php
... lines 1 - 7
class DailyStatsDateFilter implements FilterInterface
{
public function apply(Request $request, bool $normalization, array $attributes, array &$context)
{
}
public function getDescription(string $resourceClass): array
{
}
}

The only difference is that the apply() method has different arguments than filterProperty()... which makes sense because that method was all about querying via Doctrine.

Before we start filling this in, go to src/Entity/DailyStats.php so we can use the filter. So @ApiFilter(), hit tab to auto-complete that - and DailyStatsDateFilter::class... but this time we need to manually add the use statement: use DailyStatsDateFilter:

60 lines src/Entity/DailyStats.php
... lines 1 - 8
use App\ApiPlatform\DailyStatsDateFilter;
... lines 10 - 11
/**
... lines 13 - 22
* @ApiFilter(DailyStatsDateFilter::class)
*/
class DailyStats
{
... lines 27 - 58
}

Now that we've activated the filter for this resource, let's jump straight into getDescription(). This will be exactly like what we did in CheeseSearchFilter. In fact, let's go steal our code! Copy the return statement from the other filter... and paste it here. This time the query parameter will be called from, keep 'property' => null, type string is good, required false is good, but tweak the description:

Tip

In Api Platform 2.6 and higher, the description key doesn't live under openapi: it lives on the same level as the other options.

From date e.g. 2020-09-01

28 lines src/ApiPlatform/DailyStatsDateFilter.php
... lines 1 - 7
class DailyStatsDateFilter implements FilterInterface
{
... lines 10 - 13
public function getDescription(string $resourceClass): array
{
return [
'from' => [
'property' => null,
'type' => 'string',
'required' => false,
'openapi' => [
'description' => 'From date e.g. 2020-09-01',
],
]
];
}
}

The apply() method is still empty, but this should be enough to see the filter in the docs. Refresh that page, open the DailyStats collection operation and... there it is!

Adding the Filter Logic

But... how can we make this filter actually work? Well, forget about the filter system for a minute. No matter what fanciness we do, it's 100% up to our data provider to return the collection of data that will be shown.

What I mean is, we're not going to return this DailyStatsPaginator object and then expect some other system to somehow magically filter those results:

46 lines src/DataProvider/DailyStatsProvider.php
... lines 1 - 13
class DailyStatsProvider implements CollectionDataProviderInterface, ItemDataProviderInterface, RestrictedDataProviderInterface
{
... lines 16 - 24
public function getCollection(string $resourceClass, string $operationName = null)
{
list($page, $offset, $limit) = $this->pagination->getPagination($resourceClass, $operationName);
return new DailyStatsPaginator(
$this->statsHelper,
$page,
$limit
);
}
... lines 35 - 44
}

Nope, if we want DailyStats to have some filters, we need to handle that logic inside getCollection() so that the items inside the paginator represent the filtered items.

So before we really think about reading query parameters or integrating with our filter class, let's first focus on making our DailyStatsProvider able to filter the results by date.

And actually, most of the work of figuring out which results to return is done by the paginator. So let's jump into DailyStatsPaginator.

Down here, getIterator() is where we use StatsHelper to fetch all of the objects:

63 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 46
public function getIterator()
{
if ($this->dailyStatsIterator === null) {
$offset = (($this->getCurrentPage() - 1) * $this->getItemsPerPage());
$this->dailyStatsIterator = new \ArrayIterator(
$this->statsHelper->fetchMany(
$this->getItemsPerPage(),
$offset
)
);
}
return $this->dailyStatsIterator;
}
}

And, it already has a type of filtering: it returns a subset of the items based on what page we're on.

And fortunately, if we jump into src/Service/StatsHelper.php, the fetchMany() method already has a third argument called $criteria, which supports from and to keys, which are both DateTime objects:

113 lines src/Service/StatsHelper.php
... lines 1 - 7
class StatsHelper
{
... lines 10 - 16
/**
* @param array An array of criteria to limit the results
* Supported keys are:
* * from DateTimeInterface
* * to DateTimeInterface
* @return array|DailyStats[]
*/
public function fetchMany(int $limit = null, int $offset = null, array $criteria = [])
{
... lines 26 - 56
}
... lines 58 - 111
}

Basically, we can already pass a from key on the 3rd argument to filter exactly like we want. The boring work was done for us. Yay!

Ok, let's think: in order for DailyStatsPaginator to be able to return the correct results, it needs to know what the from date is. To store that info, add a property: a new private $fromDate. Above this, I'll document that this will be a \DateTimeInterface or null if it's not set:

77 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 13
/**
* @var \DateTimeInterface|null
*/
private $fromDate;
... lines 18 - 75
}

Then, at the bottom, go to "Code"->"Generate" - or Command+N on a Mac - select setters, and generate the setFromDate() method. Oh, but I'll remove the nullable type:

77 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 71
public function setFromDate(\DateTimeInterface $fromDate)
{
$this->fromDate = $fromDate;
}
}

If you call this method... I'll assume that you do have a DateTime that you want to use. We'll see who sets this in a minute.

But assuming that this is set, we can use it inside of getIterator(). Add $criteria equals an empty array. Then, if we have $this->fromDate, say $criteria['from'] = $this->fromDate:

77 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 50
public function getIterator()
{
if ($this->dailyStatsIterator === null) {
$offset = (($this->getCurrentPage() - 1) * $this->getItemsPerPage());
$criteria = [];
if ($this->fromDate) {
$criteria['from'] = $this->fromDate;
}
... lines 60 - 66
}
... lines 68 - 69
}
... lines 71 - 75
}

Finally, pass $criteria as that third argument to fetchMany():

77 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 50
public function getIterator()
{
if ($this->dailyStatsIterator === null) {
... lines 54 - 59
$this->dailyStatsIterator = new \ArrayIterator(
$this->statsHelper->fetchMany(
$this->getItemsPerPage(),
$offset,
$criteria
)
);
}
... lines 68 - 69
}
... lines 71 - 75
}

This class is ready! Let's make sure it's working by going to DailyStatsProvider and hard-coding a date temporarily. Let's see, remove the return statement, add $paginator = and, at the bottom return $paginator. In between add: $paginator->setFromDate(), with a new \DateTime() and 2020-08-30:

49 lines src/DataProvider/DailyStatsProvider.php
... lines 1 - 13
class DailyStatsProvider implements CollectionDataProviderInterface, ItemDataProviderInterface, RestrictedDataProviderInterface
{
... lines 16 - 24
public function getCollection(string $resourceClass, string $operationName = null)
{
list($page, $offset, $limit) = $this->pagination->getPagination($resourceClass, $operationName);
$paginator = new DailyStatsPaginator(
$this->statsHelper,
$page,
$limit
);
$paginator->setFromDate(new \DateTime('2020-08-30'));
return $paginator;
}
... lines 38 - 47
}

Let's see if it works! Back at the browser, I'll go over to my other tab. I do have a ?from=, but that query parameter is not being used yet: the filtering should use the hardcoded date.

When we refresh... let's see. Yes! It returned only 5 results starting with the hard-coded 08-30! Awesome!

Oh, but I do see one, teenie-tiny bug: it says hydra:totalItems 30. That should only say 5.

This number comes from our paginator object: the getTotalItems() method, which calls $this->statsHelper->count():

77 lines src/DataProvider/DailyStatsPaginator.php
... lines 1 - 7
class DailyStatsPaginator implements PaginatorInterface, \IteratorAggregate
{
... lines 10 - 30
public function getTotalItems(): float
{
return $this->statsHelper->count();
}
... lines 35 - 75
}

Really, the count() method should also allow an array of $criteria to be passed so that it can do the same filtering that happens in fetchMany(). But... I'll leave that for you as extra credit.

Next: this is good! We have the filtering logic working. But how can we fetch the real data from the query parameter? Well... I sort of just answered my own question! We could grab the Request object and read the query parameter directly. But there's actually a cooler, more built-in way that involves our DailyStatsDateFilter class.

Leave a comment!

Most Useful Newest Oldest
7
Login or Register to join the conversation
Scott Avatar

This is just FYI as I am using API Platform 2.6.8.

The desciption for the filter in the documentation was not working for me.

Instead of:


    return [
        'from' => [
            'property' => null,
            'type' => 'string',
            'required' => false,
            'openapi' => [
                'description' => 'From date e.g. 2020-09-01',
            ],
        ],
    ];

It looks like it is now is now:


    return [
        'from' => [
            'property' => null,
            'type' => 'string',
            'required' => false,
            'description' => 'From date e.g. 2020-09-01',
        ],
    ];

I figured it out by looking in vendor/api-platform/core/src/OpenApi/Factory/OpenApiFactory.php around line 415.

The same is true for the <b>CheeseSearchFilter</b>.


    return [
        'search' => [
            'property' => null,
            'type' => 'string',
            'required' => false,
            'openapi' => [
                'description' => 'Search across multiple fields',
            ],
        ],
    ];

becomes


    return [
        'search' => [
            'property' => null,
            'type' => 'string',
            'required' => false,
            'description' => 'Search across multiple fields',
        ],
   ];

Thanks for the Tutorials!

1 Reply
Victor Avatar

Hey Scott,

Thank you for sharing this workaround! We will investigate things further and most probably add a note. It sounds like new version of ApiPlatform changes some things.

Cheers!

Reply
Jakub Avatar
Jakub Avatar Jakub | posted 6 months ago | edited

Hi,
if someone would like to check the solution for "hydra:totalItems:" proper value, here is mine.
First, wipe out statsHelper in DailyStatsPaginator getTotalItems() method so this method will call self count() method.

    public function getTotalItems(): float
    {
//        return $this->statsHelper->count();
        return $this->count();
    }

Second, in count() method we need to count items a nested array and I did it like that:

    public function count()
    {
        $count = 0;
        $object = $this->getIterator();
        foreach ($object as $array) {
            $count += count($array);
        }
        return $count;
    }

I don't know if this solution is efficient but in this case it works. Maybe more experienced programmers might say something about this.
I hope my comment proves helpful for someone.

Jakub

Reply
Jakub Avatar

But there is a little problem with my solution. I didn't realise at first moment that after doing this I lost whole 'hydra:view' section in response body. For this moment I don't know why this happened. Maybe someone would like to help me with this.

Reply
weaverryan Avatar

Hey Jakub!

I don't know if this solution is efficient but in this case it works. Maybe more experienced programmers might say something about this.

Yea.. this is probably going to cause 1 of 2 different problems. First, I think this might only "loop" over the items on the page? So if there are 30 total items, but only 5 are showing on the page, then this would incorrectly show 5.

If it DID loop over all 30, then that is, indeed, a performance issue as you would be loading all 30 just to get the count. Of course, if you don't have a huge data set, it's not actually a problem ;).

The "correct" solution would depend on what your data source is. For example, if your items are stored in a database, you would take the query that you use to get the results and execute it a second time, but without the LIMIT & OFFSET - a this time just do do a quick COUNT. If your dataset is JSON... you could update my count() method JUST to count the number of "items" in the JSON and skip actually creating the DailyStats object.

But there is a little problem with my solution. I didn't realise at first moment that after doing this I lost whole 'hydra:view' section in response body

I'm not sure about this... I wouldn't think that this would be related to how you changed the "count" part. But let me know if I'm wrong.

Cheers!

So what you

Reply
Jakub Avatar

Ok. Now I know what's going on with this 'hydra:view' section. Whether it appears depends on the number stored in "hydra:totalItems". If this number is greater than stored in annotation "paginationItemsPerPage", then the 'hydra:view' section will appear.

1 Reply
Jakub Avatar

Anyway, thank you for anser.

Reply
Cat in space

"Houston: no signs of life"
Start the conversation!

This tutorial also works great with API Platform 2.6.
Api Platform 2.5 Symfony 5

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^2.1", // v2.5.10
        "composer/package-versions-deprecated": "^1.11", // 1.11.99
        "doctrine/annotations": "^1.0", // 1.12.1
        "doctrine/doctrine-bundle": "^2.0", // 2.1.2
        "doctrine/doctrine-migrations-bundle": "^3.0", // 3.0.2
        "doctrine/orm": "^2.4.5", // 2.8.2
        "nelmio/cors-bundle": "^2.1", // 2.1.0
        "nesbot/carbon": "^2.17", // 2.39.1
        "phpdocumentor/reflection-docblock": "^3.0 || ^4.0 || ^5.0", // 5.2.2
        "ramsey/uuid-doctrine": "^1.6", // 1.6.0
        "symfony/asset": "5.1.*", // v5.1.5
        "symfony/console": "5.1.*", // v5.1.5
        "symfony/debug-bundle": "5.1.*", // v5.1.5
        "symfony/dotenv": "5.1.*", // v5.1.5
        "symfony/expression-language": "5.1.*", // v5.1.5
        "symfony/flex": "^1.1", // v1.18.7
        "symfony/framework-bundle": "5.1.*", // v5.1.5
        "symfony/http-client": "5.1.*", // v5.1.5
        "symfony/monolog-bundle": "^3.4", // v3.5.0
        "symfony/security-bundle": "5.1.*", // v5.1.5
        "symfony/twig-bundle": "5.1.*", // v5.1.5
        "symfony/validator": "5.1.*", // v5.1.5
        "symfony/webpack-encore-bundle": "^1.6", // v1.8.0
        "symfony/yaml": "5.1.*" // v5.1.5
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.3", // 3.3.2
        "symfony/browser-kit": "5.1.*", // v5.1.5
        "symfony/css-selector": "5.1.*", // v5.1.5
        "symfony/maker-bundle": "^1.11", // v1.23.0
        "symfony/phpunit-bridge": "5.1.*", // v5.1.5
        "symfony/stopwatch": "5.1.*", // v5.1.5
        "symfony/twig-bundle": "5.1.*", // v5.1.5
        "symfony/web-profiler-bundle": "5.1.*", // v5.1.5
        "zenstruck/foundry": "^1.1" // v1.8.0
    }
}
Edit on GitHub
Previous Chapter
Next Chapter
userVoice