From 216d4791ce98092ba7ea7b58995365ae1990068e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 27 Feb 2017 21:41:27 +0100 Subject: [PATCH 1/7] Add an example of custom filter --- core/filters.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 5 deletions(-) diff --git a/core/filters.md b/core/filters.md index 6c88bc64129..369292c0a0b 100644 --- a/core/filters.md +++ b/core/filters.md @@ -396,15 +396,104 @@ It means that the filter will be **silently** ignored if the property: Custom filters can be written by implementing the `ApiPlatform\Core\Api\FilterInterface` interface. -If you use [custom data providers](data-providers.md), they must support filtering and be aware of active filters to work -properly. +API Platform provides a convenient way to create Doctrine ORM filters. If you use [custom data providers](data-providers.md), +you can still create filters by implementing the previously mentioned interface, but - as API Platform isn't aware of your +persistence system's internals - you have to create the filtering logic by yourself. ### Creating Custom Doctrine ORM Filters -Doctrine ORM filters must implement the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\FilterInterface`. -They can interact directly with the Doctrine `QueryBuilder`. +Doctrine filters can access to the HTTP request (Symfony's `Request` object) and to the `QueryBuilder` instance used to +retrieve data from the database. They are only applied to collections. If you want to deal with the DQL query generated +to retrieve items, or don't need to access the HTTP request, [extensions](extensions.md) are the way to go. -A convenient abstract class is also shipped with the bundle: `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter` +A Doctrine ORM filter is basically a class implementing the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\FilterInterface`. +API Platform includes a convenient abstract class implementing this interface and providing utility methods: `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\AbstractFilter` + +In the following example, we create a class to filter a collection by applying a regexp to a property. The `REGEXP` DQL +function used in this example can be found in the [`DoctrineExtensions`](https://github.com/beberlei/DoctrineExtensions) +library. This library must be properly installed and registered to use this example (works only with MySQL). + +```php +generateParameterName($property); // Generate a unique parameter name to avoid collisions with other filters + $queryBuilder + ->andWhere(sprintf('REGEXP(o.%s, :%s) = 1', $property, $parameterName)) + ->setParameter($parameterName, $value); + } + + // This function is only used to hook in documentation generators (supported by Swagger and Hydra) + public function getDescription(string $resourceClass): array + { + $description = []; + foreach ($this->properties as $property => $strategy) { + $description['regexp_'.$property] = [ + 'property' => $property, + 'type' => 'string', + 'required' => false, + 'swagger' => ['description' => 'Filter using a regex. This will appear in the Swagger documentation!'], + ]; + } + + return $description; + } +} +``` + +Then, register this filter as a service: + +```yaml +services: + 'AppBundle\Filter\RegexpFilter': + class: 'AppBundle\Filter\RegexpFilter' + autowire: true # See the next example for a plain old definition + tags: [ { name: 'api_platform.filter', id: 'regexp' } ] +``` + +In the previous example, the filter can be applied on any property. However, thanks to the `AbstractFilter` class, +it can also be enabled for some properties: + +services: + 'AppBundle\Filter\RegexpFilter': + class: 'AppBundle\Filter\RegexpFilter' + arguments: [ '@doctrine', '@request_stack', '@?logger', { email: ~, anOtherProperty: ~ } ] + tags: [ { name: 'api_platform.filter', id: 'regexp' } ] +``` + +Finally, add this filter to resources you want: + +```php + Date: Tue, 28 Feb 2017 21:29:00 +0100 Subject: [PATCH 2/7] Fix @Simperfit's comments --- core/filters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/filters.md b/core/filters.md index 369292c0a0b..b08f3f27547 100644 --- a/core/filters.md +++ b/core/filters.md @@ -398,7 +398,7 @@ interface. API Platform provides a convenient way to create Doctrine ORM filters. If you use [custom data providers](data-providers.md), you can still create filters by implementing the previously mentioned interface, but - as API Platform isn't aware of your -persistence system's internals - you have to create the filtering logic by yourself. +persistence system's internals - you have to create the filtering logic by yourself. ### Creating Custom Doctrine ORM Filters @@ -472,7 +472,7 @@ services: tags: [ { name: 'api_platform.filter', id: 'regexp' } ] ``` -Finally, add this filter to resources you want: +Finally, add this filter to resources you want to be filtered: ```php Date: Thu, 2 Mar 2017 07:20:16 +0100 Subject: [PATCH 3/7] on|off is not supported in Boolean Filter anymore --- core/filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/filters.md b/core/filters.md index 6c88bc64129..214930017d5 100644 --- a/core/filters.md +++ b/core/filters.md @@ -152,7 +152,7 @@ constant directly. The boolean filter allows you to search on boolean fields and values. -Syntax: `?property=[on|off|true|false|0|1]` +Syntax: `?property=[true|false|1|0]` You can either use TRUE or true, the parameters are case insensitive. From e30b91240427ef00f06f0b1558680ebe1c7f5087 Mon Sep 17 00:00:00 2001 From: Tim Date: Wed, 29 Mar 2017 15:47:09 +0200 Subject: [PATCH 4/7] fix minor visual bug --- core/filters.md | 1 + 1 file changed, 1 insertion(+) diff --git a/core/filters.md b/core/filters.md index c734deab989..35520c0acdb 100644 --- a/core/filters.md +++ b/core/filters.md @@ -465,6 +465,7 @@ services: In the previous example, the filter can be applied on any property. However, thanks to the `AbstractFilter` class, it can also be enabled for some properties: +```yaml services: 'AppBundle\Filter\RegexpFilter': class: 'AppBundle\Filter\RegexpFilter' From 565648215410c0f776e1271128266398e8e58884 Mon Sep 17 00:00:00 2001 From: abluchet Date: Fri, 31 Mar 2017 17:55:00 +0200 Subject: [PATCH 5/7] Fix trough through --- core/getting-started.md | 4 ++-- core/serialization-groups-and-relations.md | 4 ++-- deployment/heroku.md | 2 +- deployment/index.md | 2 +- distribution/testing.md | 6 +++--- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/core/getting-started.md b/core/getting-started.md index 6833988aaf2..40db0aadc60 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -56,7 +56,7 @@ API Platform Core is able to automatically expose entities mapped as "API resour operations. To expose your entities, you can use Docblock annotations, XML and YAML configuration files. -Here is an example of entities mapped using annotations which will be exposed trough a REST API: +Here is an example of entities mapped using annotations which will be exposed through a REST API: ```php Date: Wed, 12 Apr 2017 17:54:50 +0800 Subject: [PATCH 6/7] Fix list indentation in TOC (index.md) --- index.md | 158 +++++++++++++++++++++++++++---------------------------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/index.md b/index.md index 44f5b35a440..88dd04fd68c 100644 --- a/index.md +++ b/index.md @@ -2,105 +2,105 @@ ## API Platform Distribution: create a powerful APIs with ease -1. [Creating a Fully Featured API in 5 Minutes](distribution/index.md) -2. [Testing and Specifying the API](distribution/testing.md) +1. [Creating a Fully Featured API in 5 Minutes](distribution/index.md) +2. [Testing and Specifying the API](distribution/testing.md) ## API Platform Core library -1. [Introduction](core/index.md) -2. [Getting Started](core/getting-started.md) - 1. [Installing API Platform Core](core/getting-started.md#installing-api-platform-core) - 2. [Before Reading this Documentation](core/getting-started.md#before-reading-this-documentation) - 3. [Mapping the Entities](core/getting-started.md#mapping-the-entities) -3. [Configuration](core/configuration.md) -4. [Operations](core/operations.md) - 1. [Enabling and Disabling Operations](core/operations.md#enabling-and-disabling-operations) - 2. [Configuring Operations](core/operations.md#configuring-operations) - 3. [Creating Custom Operations and Controllers](core/operations.md#creating-custom-operations-and-controllers) -5. [Filters](core/filters.md) - 1. [Search Filter](core/filters.md#search-filter) - 2. [Date Filter](core/filters.md#date-filter) - 1. [Managing `null` Values](core/filters.md#managing-null-values) - 3. [Boolean Filter](core/filters.md#boolean-filter) - 4. [Numeric Filter](core/filters.md#numeric-filter) - 5. [Order filter](core/filters.md#order-filter) - 1. [Using a Custom Order Query Parameter Name](core/filters.md#using-a-custom-order-query-parameter-name) - 6. [Filtering on Nested Properties](core/filters.md#filtering-on-nested-properties) - 7. [Enabling a Filter for All Properties of a Resource](core/filters.md#enabling-a-filter-for-all-properties-of-a-resource) - 8. [Creating Custom Filters](core/filters.md#creating-custom-filters) - 1. [Creating Custom Doctrine ORM Filters](core/filters.md#creating-custom-doctrine-orm-filters) - 2. [Overriding Extraction of Properties from the Request](core/filters.md#overriding-extraction-of-properties-from-the-request) -6. [Serialization Groups and Relations](core/serialization-groups-and-relations.md) - 1. [Configuration](core/serialization-groups-and-relations.md#configuration) - 2. [Using Different Serialization Groups per Operation](core/serialization-groups-and-relations.md#embedding-relations) - 3. [Embedding Relations](core/serialization-groups-and-relations.md#embedding-relations) - 1. [Normalization](core/serialization-groups-and-relations.md#normalization) - 2. [Denormalization](core/serialization-groups-and-relations.md#denormalization) - 3. [Changing the Serialization Context Dynamically](core/serialization-groups-and-relations.md#changing-the-serialization-context-dynamically) - 4. [Name Conversion](core/serialization-groups-and-relations.md#name-conversion) - 5. [Entity Identifier Case](core/serialization-groups-and-relations.md#entity-identifier-case) - 6. [Writable Entity Identifier](core/serialization-groups-and-relations.md#writable-entity-identifier) - 7. [Embedding the Context](core/serialization-groups-and-relations.md#embedding-the-context) -7. [Validation](core/validation.md) - 1. [Using Validation Groups](core/validation.md#using-validation-groups) - 2. [Dynamic Validation Groups](core/validation.md#dynamic-validation-groups) -8. [Pagination](core/pagination.md) - 1. [Disabling the Pagination](core/pagination.md#disabling-the-pagination) - 2. [Changing the Number of Items per Page](core/pagination.md#changing-the-number-of-items-per-page) -9. [The Event System](core/events.md) +1. [Introduction](core/index.md) +2. [Getting Started](core/getting-started.md) + 1. [Installing API Platform Core](core/getting-started.md#installing-api-platform-core) + 2. [Before Reading this Documentation](core/getting-started.md#before-reading-this-documentation) + 3. [Mapping the Entities](core/getting-started.md#mapping-the-entities) +3. [Configuration](core/configuration.md) +4. [Operations](core/operations.md) + 1. [Enabling and Disabling Operations](core/operations.md#enabling-and-disabling-operations) + 2. [Configuring Operations](core/operations.md#configuring-operations) + 3. [Creating Custom Operations and Controllers](core/operations.md#creating-custom-operations-and-controllers) +5. [Filters](core/filters.md) + 1. [Search Filter](core/filters.md#search-filter) + 2. [Date Filter](core/filters.md#date-filter) + 1. [Managing `null` Values](core/filters.md#managing-null-values) + 3. [Boolean Filter](core/filters.md#boolean-filter) + 4. [Numeric Filter](core/filters.md#numeric-filter) + 5. [Order filter](core/filters.md#order-filter) + 1. [Using a Custom Order Query Parameter Name](core/filters.md#using-a-custom-order-query-parameter-name) + 6. [Filtering on Nested Properties](core/filters.md#filtering-on-nested-properties) + 7. [Enabling a Filter for All Properties of a Resource](core/filters.md#enabling-a-filter-for-all-properties-of-a-resource) + 8. [Creating Custom Filters](core/filters.md#creating-custom-filters) + 1. [Creating Custom Doctrine ORM Filters](core/filters.md#creating-custom-doctrine-orm-filters) + 2. [Overriding Extraction of Properties from the Request](core/filters.md#overriding-extraction-of-properties-from-the-request) +6. [Serialization Groups and Relations](core/serialization-groups-and-relations.md) + 1. [Configuration](core/serialization-groups-and-relations.md#configuration) + 2. [Using Different Serialization Groups per Operation](core/serialization-groups-and-relations.md#embedding-relations) + 3. [Embedding Relations](core/serialization-groups-and-relations.md#embedding-relations) + 1. [Normalization](core/serialization-groups-and-relations.md#normalization) + 2. [Denormalization](core/serialization-groups-and-relations.md#denormalization) + 3. [Changing the Serialization Context Dynamically](core/serialization-groups-and-relations.md#changing-the-serialization-context-dynamically) + 4. [Name Conversion](core/serialization-groups-and-relations.md#name-conversion) + 5. [Entity Identifier Case](core/serialization-groups-and-relations.md#entity-identifier-case) + 6. [Writable Entity Identifier](core/serialization-groups-and-relations.md#writable-entity-identifier) + 7. [Embedding the Context](core/serialization-groups-and-relations.md#embedding-the-context) +7. [Validation](core/validation.md) + 1. [Using Validation Groups](core/validation.md#using-validation-groups) + 2. [Dynamic Validation Groups](core/validation.md#dynamic-validation-groups) +8. [Pagination](core/pagination.md) + 1. [Disabling the Pagination](core/pagination.md#disabling-the-pagination) + 2. [Changing the Number of Items per Page](core/pagination.md#changing-the-number-of-items-per-page) +9. [The Event System](core/events.md) 10. [Content Negotiation](core/content-negotiation.md) - 1. [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats) - 2. [Registering a Custom Serializer](core/content-negotiation.md#registering-a-custom-serializer) - 3. [Creating a Responder](core/content-negotiation.md#creating-a-responder) + 1. [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats) + 2. [Registering a Custom Serializer](core/content-negotiation.md#registering-a-custom-serializer) + 3. [Creating a Responder](core/content-negotiation.md#creating-a-responder) 11. [Using External JSON-LD Vocabularies](core/external-vocabularies.md) 12. [Extending JSON-LD context](core/extending-jsonld-context.md) 13. [Data Providers](core/data-providers.md) - 1. [Custom Collection Data Provider](core/data-providers.md#creating-a-custom-data-provider#custom-collection-data-provider) - 2. [Custom Item Data Provider](core/data-providers.md#returning-a-paged-collection#custom-item-data-provider) + 1. [Custom Collection Data Provider](core/data-providers.md#creating-a-custom-data-provider#custom-collection-data-provider) + 2. [Custom Item Data Provider](core/data-providers.md#returning-a-paged-collection#custom-item-data-provider) 14. [Extensions](core/extensions.md) - 1. [Custom Extension](core/extensions.md#custom-extension) - 2. [Filter upon the current user](core/extensions.md#example) + 1. [Custom Extension](core/extensions.md#custom-extension) + 2. [Filter upon the current user](core/extensions.md#example) 16. [Security](core/security.md) 17. [Performance](core/performance.md) - 1. [Enabling the Metadata Cache](core/performance.md#enabling-the-metadata-cache) - 2. [Using PPM (PHP-PM)](core/performance.md#using-ppm-php-pm) - 3. [Doctrine Queries and Indexes](core/performance.md#doctrine-queries-and-indexes) - 1. [Search Filter](core/performance.md#search-filter) - 2. [Eager Loading](core/performance.md#eager-loading) - 1. [Max Joins](core/performance.md#max-joins) - 2. [Force Eager](core/performance.md#force-eager) - 3. [Override at Resource and Operation Level](core/performance.md#override-at-resource-and-operation-level) - 4. [Disable Eager Loading](core/performance.md#disable-eager-loading) + 1. [Enabling the Metadata Cache](core/performance.md#enabling-the-metadata-cache) + 2. [Using PPM (PHP-PM)](core/performance.md#using-ppm-php-pm) + 3. [Doctrine Queries and Indexes](core/performance.md#doctrine-queries-and-indexes) + 1. [Search Filter](core/performance.md#search-filter) + 2. [Eager Loading](core/performance.md#eager-loading) + 1. [Max Joins](core/performance.md#max-joins) + 2. [Force Eager](core/performance.md#force-eager) + 3. [Override at Resource and Operation Level](core/performance.md#override-at-resource-and-operation-level) + 4. [Disable Eager Loading](core/performance.md#disable-eager-loading) 18. [Operation Path Naming](core/operation-path-naming.md) - 1. [Configuration](core/operation-path-naming.md#configuration) - 2. [Create a Custom Operation Path Naming](core/operation-path-naming.md#create-a-custom-operation-path-resolver) - 1. [Defining the Operation Path Naming](core/operation-path-naming.md#defining-the-operation-path-resolver) - 2. [Registering the Service](core/operation-path-naming.md#registering-the-service) - 3. [Configure it](core/operation-path-naming.md#configure-it) -19. [Accept `application/x-www-form-urlencoded` Form Data] (core/form-data.md) + 1. [Configuration](core/operation-path-naming.md#configuration) + 2. [Create a Custom Operation Path Naming](core/operation-path-naming.md#create-a-custom-operation-path-resolver) + 1. [Defining the Operation Path Naming](core/operation-path-naming.md#defining-the-operation-path-resolver) + 2. [Registering the Service](core/operation-path-naming.md#registering-the-service) + 3. [Configure it](core/operation-path-naming.md#configure-it) +19. [Accept `application/x-www-form-urlencoded` Form Data](core/form-data.md) 20. [FOSUserBundle Integration](core/fosuser-bundle.md) - 1. [Creating a `User` Entity with Serialization Groups](core/fosuser-bundle.md#creating-a-user-entity-with-serialization-groups) -21. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md) + 1. [Creating a `User` Entity with Serialization Groups](core/fosuser-bundle.md#creating-a-user-entity-with-serialization-groups) +21. [Adding a JWT authentication using LexikJWTAuthenticationBundle](core/jwt.md) 22. [NelmioApiDocBundle integration](core/nelmio-api-doc.md) 23. [AngularJS Integration](core/angularjs-integration.md) - 1. [Restangular](core/angularjs-integration.md#restangular) - 2. [ng-admin](core/angularjs-integration.md#ng-admin) + 1. [Restangular](core/angularjs-integration.md#restangular) + 2. [ng-admin](core/angularjs-integration.md#ng-admin) ## Schema Generator: Generate Data Models from Open Vocabularies -1. [Introduction](schema-generator/index.md) -2. [Getting Started](schema-generator/getting-started.md) -3. [Configuration](schema-generator/configuration.md) +1. [Introduction](schema-generator/index.md) +2. [Getting Started](schema-generator/getting-started.md) +3. [Configuration](schema-generator/configuration.md) ## Deployment -1. [Introduction](deployment/index.md) -2. [Deploying an API Platform App on Heroku](deployment/heroku.md) -3. [Using API Platform with Docker](deployment/docker.md) +1. [Introduction](deployment/index.md) +2. [Deploying an API Platform App on Heroku](deployment/heroku.md) +3. [Using API Platform with Docker](deployment/docker.md) ## Extra -1. [The project's philosophy](philosophy.md) -2. [Troubleshooting](troubleshooting.md) -3. [Contribution guide](https://github.com/api-platform/api-platform/blob/master/CONTRIBUTING.md) -4. [Contributor Code Of Conduct](conduct.md) +1. [The project's philosophy](philosophy.md) +2. [Troubleshooting](troubleshooting.md) +3. [Contribution guide](https://github.com/api-platform/api-platform/blob/master/CONTRIBUTING.md) +4. [Contributor Code Of Conduct](conduct.md) From 314cf71a4360c6bfa387611b6279416f5d372661 Mon Sep 17 00:00:00 2001 From: Sebastien COLLADO Date: Tue, 25 Apr 2017 11:39:49 +0200 Subject: [PATCH 7/7] resources.xml modifications related to PR #1080 Adds XML namespace to api_platform/resources.xml file --- core/getting-started.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/core/getting-started.md b/core/getting-started.md index 40db0aadc60..4e2869abef7 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -173,7 +173,10 @@ As an alternative to annotations, you can map entity classes using XML or YAML: - +