[Laravel] Utilising Filters on `ApiResource` or `Operation`

[jedkirby]

API Platform version(s) affected:4.0.17

Description
When a filter is added to either an ApiResource, or a Operation such as GetCollection, the Swagger documentation fails on the following error:

2025-02-14 15:04:22 NOTICE: PHP message: PHP Fatal error:  Uncaught Error: Call to a member function has() on null in /var/www/html/vendor/api-platform/openapi/Factory/OpenApiFactory.php:584
2025-02-14 15:04:22 Stack trace:
2025-02-14 15:04:22 #0 /var/www/html/vendor/api-platform/openapi/Factory/OpenApiFactory.php(254): ApiPlatform\OpenApi\Factory\OpenApiFactory->getFiltersParameters(Object(ApiPlatform\Metadata\GetCollection))
2025-02-14 15:04:22 #1 /var/www/html/vendor/api-platform/openapi/Factory/OpenApiFactory.php(110): ApiPlatform\OpenApi\Factory\OpenApiFactory->collectPaths(Object(App\Api\Metadata\CustomerApiResource), Object(ApiPlatform\Metadata\Resource\ResourceMetadataCollection), Object(ApiPlatform\OpenApi\Model\Paths), Object(ArrayObject), Object(ArrayObject), Array)
2025-02-14 15:04:22 #2 /var/www/html/vendor/api-platform/laravel/State/SwaggerUiProvider.php(84): ApiPlatform\OpenApi\Factory\OpenApiFactory->__invoke(Array)
2025-02-14 15:04:22 #3 /var/www/html/vendor/api-platform/laravel/State/ValidateProvider.php(43): ApiPlatform\Laravel\State\SwaggerUiProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #4 /var/www/html/vendor/api-platform/state/Provider/DeserializeProvider.php(56): ApiPlatform\Laravel\State\ValidateProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #5 /var/www/html/vendor/api-platform/laravel/JsonApi/State/JsonApiProvider.php(36): ApiPlatform\State\Provider\DeserializeProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #6 /var/www/html/vendor/api-platform/state/Provider/SecurityParameterProvider.php(39): ApiPlatform\Laravel\JsonApi\State\JsonApiProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #7 /var/www/html/vendor/api-platform/laravel/State/ParameterValidatorProvider.php(87): ApiPlatform\State\Provider\SecurityParameterProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #8 /var/www/html/vendor/api-platform/state/Provider/ParameterProvider.php(103): ApiPlatform\Laravel\State\ParameterValidatorProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #9 /var/www/html/vendor/api-platform/laravel/State/AccessCheckerProvider.php(45): ApiPlatform\State\Provider\ParameterProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #10 /var/www/html/vendor/api-platform/state/Provider/ContentNegotiationProvider.php(51): ApiPlatform\Laravel\State\AccessCheckerProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #11 /var/www/html/vendor/api-platform/laravel/Controller/ApiPlatformController.php(79): ApiPlatform\State\Provider\ContentNegotiationProvider->provide(Object(ApiPlatform\Metadata\Error), Array, Array)
2025-02-14 15:04:22 #12 /var/www/html/vendor/api-platform/laravel/Exception/ErrorHandler.php(161): ApiPlatform\Laravel\Controller\ApiPlatformController->__invoke(Object(Illuminate\Http\Request))
2025-02-14 15:04:22 #13 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Exceptions/Handler.php(685): ApiPlatform\Laravel\Exception\ErrorHandler->ApiPlatform\Laravel\Exception\{closure}(Object(Symfony\Component\ErrorHandler\Error\FatalError), Object(Illuminate\Http\Request))
2025-02-14 15:04:22 #14 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Exceptions/Handler.php(586): Illuminate\Foundation\Exceptions\Handler->renderViaCallbacks(Object(Illuminate\Http\Request), Object(Symfony\Component\ErrorHandler\Error\FatalError))
2025-02-14 15:04:22 #15 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(225): Illuminate\Foundation\Exceptions\Handler->render(Object(Illuminate\Http\Request), Object(Symfony\Component\ErrorHandler\Error\FatalError))
2025-02-14 15:04:22 #16 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(202): Illuminate\Foundation\Bootstrap\HandleExceptions->renderHttpResponse(Object(Symfony\Component\ErrorHandler\Error\FatalError))
2025-02-14 15:04:22 #17 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(238): Illuminate\Foundation\Bootstrap\HandleExceptions->handleException(Object(Symfony\Component\ErrorHandler\Error\FatalError))
2025-02-14 15:04:22 #18 /var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(290): Illuminate\Foundation\Bootstrap\HandleExceptions->handleShutdown()
2025-02-14 15:04:22 #19 [internal function]: Illuminate\Foundation\Bootstrap\HandleExceptions->Illuminate\Foundation\Bootstrap\{closure}()
2025-02-14 15:04:22 #20 {main}
2025-02-14 15:04:22   thrown in /var/www/html/vendor/api-platform/openapi/Factory/OpenApiFactory.php on line 584

Furthermore, hitting the endpoint not via the documentation, i.e. using application/json, doesn't trigger the error, but it also does not fire the Filter as is expected.

[jedkirby]

Well this will be the reason: https://github.com/api-platform/laravel/blob/v4.0.17/ApiPlatformProvider.php#L842

[jedkirby]

I guess my questions is: are filters not implemented within the Laravel implementation for usage on a resource or operation?

[soyuka]

can you show some code? filters are declared using the QueryParameter class.

[jedkirby]

@soyuka - it’s adding filters to an ApiResource globally, or to a specific resource operation, I.e. Get.

I’m using Filters within QueryParameters and that’s fine, but adding them as mentioned above means they do not get processed, and furthermore, breaks the documentation.

If you simply add a filter to an ApiResource whilst using a default Laravel install, and try to use the documentation (and/or utilise the global filter), you’ll see the issues.

[soyuka]

show some code please I don't understand what you're trying to do

[jedkirby]

Sure, so I need to have the following within a Laravel Model ApiResource definition:

#[ApiResource(
    shortName: 'CustomerCase',
    uriTemplate: '/customer/cases',
    filters: [
        CustomerSpecificFilter::class,
    ],
    operations: [
        new GetCollection,
    ],
)]
class Cases extends Model
{

...

This is because I want to apply a filter to all requests to this endpoint, regardless.

I know I can do the following:

#[QueryParameter(key: 'sort[:property]', filter: GenericSorting::class)]

But this filter is only triggered when the sort param is provided in the request.

[soyuka]

A filter is always linked to a parameter, for this you need to use query extensions (ApiPlatform\Laravel\Eloquent\Extension\QueryExtensionInterface):

core/src/Laravel/ApiPlatformProvider.php

Lines 440 to 447 in ad54075

	$this->app->bind(FilterQueryExtension::class, function (Application $app) {
	$tagged = iterator_to_array($app->tagged(EloquentFilterInterface::class));
	return new FilterQueryExtension(new ServiceLocator($tagged));
	});
	$this->app->tag([FilterQueryExtension::class], QueryExtensionInterface::class);

An example is our FilterExtensionInterface, basically create your own extension that does the filtering you want.

A more even more powerful solution is to use a ProviderInterface for that, you can decorate our own CollectionProvider and alter the query and/or the results.