fix(laravel): jsonapi query parameters (page, sort, fields and include) (#6876)

soyuka · web-flow · commit bb5f03de756d · 2024-12-20T10:36:56.000+01:00
diff --git a/ApiPlatformProvider.php b/ApiPlatformProvider.php
@@ -57,6 +57,8 @@
 use ApiPlatform\Hydra\Serializer\HydraPrefixNameConverter;
 use ApiPlatform\Hydra\Serializer\PartialCollectionViewNormalizer as HydraPartialCollectionViewNormalizer;
 use ApiPlatform\Hydra\State\HydraLinkProcessor;
+use ApiPlatform\JsonApi\Filter\SparseFieldset;
+use ApiPlatform\JsonApi\Filter\SparseFieldsetParameterProvider;
 use ApiPlatform\JsonApi\JsonSchema\SchemaFactory as JsonApiSchemaFactory;
 use ApiPlatform\JsonApi\Serializer\CollectionNormalizer as JsonApiCollectionNormalizer;
 use ApiPlatform\JsonApi\Serializer\EntrypointNormalizer as JsonApiEntrypointNormalizer;
@@ -84,6 +86,8 @@
 use ApiPlatform\Laravel\Eloquent\Filter\DateFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\FilterInterface as EloquentFilterInterface;
+use ApiPlatform\Laravel\Eloquent\Filter\JsonApi\SortFilter;
+use ApiPlatform\Laravel\Eloquent\Filter\JsonApi\SortFilterParameterProvider;
 use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\RangeFilter;
@@ -106,6 +110,7 @@
 use ApiPlatform\Laravel\Exception\ErrorHandler;
 use ApiPlatform\Laravel\GraphQl\Controller\EntrypointController as GraphQlEntrypointController;
 use ApiPlatform\Laravel\GraphQl\Controller\GraphiQlController;
+use ApiPlatform\Laravel\JsonApi\State\JsonApiProvider;
 use ApiPlatform\Laravel\Metadata\CachePropertyMetadataFactory;
 use ApiPlatform\Laravel\Metadata\CachePropertyNameCollectionMetadataFactory;
 use ApiPlatform\Laravel\Metadata\CacheResourceCollectionMetadataFactory;
@@ -421,7 +426,15 @@ public function register(): void
 
         $this->app->bind(OperationMetadataFactoryInterface::class, OperationMetadataFactory::class);
 
-        $this->app->tag([EqualsFilter::class, PartialSearchFilter::class, DateFilter::class, OrderFilter::class, RangeFilter::class], EloquentFilterInterface::class);
+        $this->app->tag([
+            EqualsFilter::class,
+            PartialSearchFilter::class,
+            DateFilter::class,
+            OrderFilter::class,
+            RangeFilter::class,
+            SortFilter::class,
+            SparseFieldset::class,
+        ], EloquentFilterInterface::class);
 
         $this->app->bind(FilterQueryExtension::class, function (Application $app) {
             $tagged = iterator_to_array($app->tagged(EloquentFilterInterface::class));
@@ -468,6 +481,12 @@ public function register(): void
             return new DeserializeProvider($app->make(ValidateProvider::class), $app->make(SerializerInterface::class), $app->make(SerializerContextBuilderInterface::class));
         });
 
+        if (class_exists(JsonApiProvider::class)) {
+            $this->app->extend(DeserializeProvider::class, function (ProviderInterface $inner, Application $app) {
+                return new JsonApiProvider($inner);
+            });
+        }
+
         $this->app->tag([PropertyFilter::class], SerializerFilterInterface::class);
 
         $this->app->singleton(SerializerFilterParameterProvider::class, function (Application $app) {
@@ -477,7 +496,10 @@ public function register(): void
         });
         $this->app->alias(SerializerFilterParameterProvider::class, 'api_platform.serializer.filter_parameter_provider');
 
-        $this->app->tag([SerializerFilterParameterProvider::class], ParameterProviderInterface::class);
+        $this->app->singleton(SortFilterParameterProvider::class, function (Application $app) {
+            return new SortFilterParameterProvider();
+        });
+        $this->app->tag([SerializerFilterParameterProvider::class, SortFilterParameterProvider::class, SparseFieldsetParameterProvider::class], ParameterProviderInterface::class);
 
         $this->app->singleton('filters', function (Application $app) {
             return new ServiceLocator(array_merge(
diff --git a/Eloquent/Filter/JsonApi/SortFilter.php b/Eloquent/Filter/JsonApi/SortFilter.php
@@ -0,0 +1,62 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Laravel\Eloquent\Filter\JsonApi;
+
+use ApiPlatform\Laravel\Eloquent\Filter\FilterInterface;
+use ApiPlatform\Metadata\JsonSchemaFilterInterface;
+use ApiPlatform\Metadata\Parameter;
+use ApiPlatform\Metadata\ParameterProviderFilterInterface;
+use ApiPlatform\Metadata\PropertiesAwareInterface;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+
+final class SortFilter implements FilterInterface, JsonSchemaFilterInterface, ParameterProviderFilterInterface, PropertiesAwareInterface
+{
+    public const ASC = 'asc';
+    public const DESC = 'desc';
+
+    /**
+     * @param Builder<Model>       $builder
+     * @param array<string, mixed> $context
+     */
+    public function apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder
+    {
+        if (!\is_array($values)) {
+            return $builder;
+        }
+
+        foreach ($values as $order => $dir) {
+            if (self::ASC !== $dir && self::DESC !== $dir) {
+                continue;
+            }
+
+            $builder->orderBy($order, $dir);
+        }
+
+        return $builder;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function getSchema(Parameter $parameter): array
+    {
+        return ['type' => 'string'];
+    }
+
+    public static function getParameterProvider(): string
+    {
+        return SortFilterParameterProvider::class;
+    }
+}
diff --git a/Eloquent/Filter/JsonApi/SortFilterParameterProvider.php b/Eloquent/Filter/JsonApi/SortFilterParameterProvider.php
@@ -0,0 +1,55 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Laravel\Eloquent\Filter\JsonApi;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Parameter;
+use ApiPlatform\State\ParameterProviderInterface;
+
+final readonly class SortFilterParameterProvider implements ParameterProviderInterface
+{
+    public function provide(Parameter $parameter, array $parameters = [], array $context = []): ?Operation
+    {
+        if (!($operation = $context['operation'] ?? null)) {
+            return null;
+        }
+
+        $parameters = $operation->getParameters();
+        $properties = $parameter->getExtraProperties()['_properties'] ?? [];
+        $value = $parameter->getValue();
+        if (!\is_string($value)) {
+            return $operation;
+        }
+
+        $values = explode(',', $value);
+        $orderBy = [];
+        foreach ($values as $v) {
+            $dir = SortFilter::ASC;
+            if (str_starts_with($v, '-')) {
+                $dir = SortFilter::DESC;
+                $v = substr($v, 1);
+            }
+
+            if (\array_key_exists($v, $properties)) {
+                $orderBy[$properties[$v]] = $dir;
+            }
+        }
+
+        $parameters->add($parameter->getKey(), $parameter->withExtraProperties(
+            ['_api_values' => $orderBy] + $parameter->getExtraProperties()
+        ));
+
+        return $operation->withParameters($parameters);
+    }
+}
diff --git a/Eloquent/Metadata/Factory/Property/EloquentPropertyNameCollectionMetadataFactory.php b/Eloquent/Metadata/Factory/Property/EloquentPropertyNameCollectionMetadataFactory.php
@@ -73,7 +73,7 @@ public function create(string $resourceClass, array $options = []): PropertyName
         }
 
         return new PropertyNameCollection(
-            array_keys($properties) // @phpstan-ignore-line
+            array_keys($properties)
         );
     }
 }
diff --git a/JsonApi/State/JsonApiProvider.php b/JsonApi/State/JsonApiProvider.php
@@ -0,0 +1,66 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Laravel\JsonApi\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProviderInterface;
+
+/**
+ * This is a copy of ApiPlatform\JsonApi\State\JsonApiProvider without the support of sort,filter and fields as these should be implemented using QueryParameters and specific Filters.
+ * At some point we want to merge both classes but for now we don't have the SortFilter inside Symfony.
+ *
+ * @internal
+ */
+final class JsonApiProvider implements ProviderInterface
+{
+    public function __construct(private readonly ProviderInterface $decorated)
+    {
+    }
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
+    {
+        $request = $context['request'] ?? null;
+
+        if (!$request || 'jsonapi' !== $request->getRequestFormat()) {
+            return $this->decorated->provide($operation, $uriVariables, $context);
+        }
+
+        $filters = $request->attributes->get('_api_filters', []);
+        $queryParameters = $request->query->all();
+
+        $pageParameter = $queryParameters['page'] ?? null;
+        if (
+            \is_array($pageParameter)
+        ) {
+            $filters = array_merge($pageParameter, $filters);
+        }
+
+        if (isset($pageParameter['offset'])) {
+            $filters['page'] = $pageParameter['offset'];
+            unset($filters['offset']);
+        }
+
+        $includeParameter = $queryParameters['include'] ?? null;
+
+        if ($includeParameter) {
+            $request->attributes->set('_api_included', explode(',', $includeParameter));
+        }
+
+        if ($filters) {
+            $request->attributes->set('_api_filters', $filters);
+        }
+
+        return $this->decorated->provide($operation, $uriVariables, $context);
+    }
+}
diff --git a/Tests/JsonApiTest.php b/Tests/JsonApiTest.php
@@ -17,6 +17,7 @@
 use Illuminate\Contracts\Config\Repository;
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
 use Orchestra\Testbench\Concerns\WithWorkbench;
 use Orchestra\Testbench\TestCase;
 use Workbench\App\Models\Author;
@@ -40,6 +41,8 @@ protected function defineEnvironment($app): void
             $config->set('api-platform.formats', ['jsonapi' => ['application/vnd.api+json']]);
             $config->set('api-platform.docs_formats', ['jsonapi' => ['application/vnd.api+json']]);
             $config->set('api-platform.resources', [app_path('Models'), app_path('ApiResource')]);
+            $config->set('api-platform.pagination.items_per_page_parameter_name', 'limit');
+
             $config->set('app.debug', true);
         });
     }
@@ -285,4 +288,37 @@ public function testNotFound(): void
             'detail' => 'Not Found',
         ], $response->json()['errors'][0]);
     }
+
+    public function testSortParameter(): void
+    {
+        BookFactory::new()->has(AuthorFactory::new())->count(10)->create();
+        DB::enableQueryLog();
+        $this->get('/api/books?sort=isbn,-name', headers: ['accept' => 'application/vnd.api+json']);
+        ['query' => $q] = DB::getQueryLog()[1];
+        $this->assertStringContainsString('order by "isbn" asc, "name" desc', $q);
+    }
+
+    public function testPageParameter(): void
+    {
+        BookFactory::new()->has(AuthorFactory::new())->count(10)->create();
+        DB::enableQueryLog();
+        $this->get('/api/books?page[limit]=1&page[offset]=2', headers: ['accept' => 'application/vnd.api+json']);
+        ['query' => $q] = DB::getQueryLog()[1];
+        $this->assertStringContainsString('select * from "books" limit 1 offset 1', $q);
+    }
+
+    public function testSparseFieldset(): void
+    {
+        BookFactory::new()->has(AuthorFactory::new())->count(10)->create();
+        $r = $this->get('/api/books?fields[book]=name,isbn&fields[author]=name&include=author', headers: ['accept' => 'application/vnd.api+json']);
+        $res = $r->json();
+        $attributes = $res['data'][0]['attributes'];
+        $this->assertArrayHasKey('name', $attributes);
+        $this->assertArrayHasKey('isbn', $attributes);
+        $this->assertArrayNotHasKey('isAvailable', $attributes);
+
+        $included = $res['included'][0]['attributes'];
+        $this->assertArrayNotHasKey('createdAt', $included);
+        $this->assertArrayHasKey('name', $included);
+    }
 }
diff --git a/workbench/app/Models/Book.php b/workbench/app/Models/Book.php
@@ -13,8 +13,10 @@
 
 namespace Workbench\App\Models;
 
+use ApiPlatform\JsonApi\Filter\SparseFieldset;
 use ApiPlatform\Laravel\Eloquent\Filter\DateFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter;
+use ApiPlatform\Laravel\Eloquent\Filter\JsonApi\SortFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\OrFilter;
 use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter;
@@ -40,6 +42,7 @@
 #[ApiResource(
     paginationEnabled: true,
     paginationItemsPerPage: 5,
+    paginationClientItemsPerPage: true,
     rules: BookFormRequest::class,
     operations: [
         new Put(),
@@ -76,6 +79,8 @@
     property: 'name'
 )]
 #[QueryParameter(key: 'properties', filter: PropertyFilter::class)]
+#[QueryParameter(key: 'fields', filter: SparseFieldset::class)]
+#[QueryParameter(key: 'sort', filter: SortFilter::class)]
 class Book extends Model
 {
     use HasFactory;

Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ public function create(string $resourceClass, array $options = []): PropertyName`
`73`	`73`	`}`
`74`	`74`
`75`	`75`	`return new PropertyNameCollection(`
`76`		`- array_keys($properties) // @phpstan-ignore-line`
	`76`	`+ array_keys($properties)`
`77`	`77`	`);`
`78`	`78`	`}`
`79`	`79`	`}`