api-platform/core#1246: configure default order on ApiResource annotation (#235)

Author: vincentchalamon

core/default-order.md

@@ -0,0 +1,64 @@
+# Overriding Default Order
+
+API Platform Core provides an easy way to override the default order of items in your collection.
+
+By default, items in the collection are ordered in ascending (ASC) order by their resource identifier(s). If you want to
+customize this order, you must add an `order` attribute on your ApiResource annotation:
+
+```php
+<?php
+
+// src/AppBundle/Entity/Book.php
+
+namespace AppBundle\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(attributes={"order"={"foo": "ASC"}})
+ */
+class Book
+{
+    // ...
+
+    /**
+     * ...
+     */
+    public $foo;
+}
+```
+
+This `order` attribute is used as an array: the key defines the order field, the values defines the direction.
+If you only specify the key, `ASC` direction will be used as default. For example, to order by `foo` & `bar`:
+
+```php
+<?php
+
+// src/AppBundle/Entity/Book.php
+
+namespace AppBundle\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(attributes={"order"={"foo", "bar"}})
+ */
+class Book
+{
+    // ...
+
+    /**
+     * ...
+     */
+    public $foo;
+
+    /**
+     * ...
+     */
+    public $bar;
+}
+```
+
+Previous chapter: [Operations](operations.md)
+
+Next chapter: [Filters](filters.md)

core/operations.md

@@ -525,4 +525,5 @@ book_special:
 
 Previous chapter: [Configuration](configuration.md)
 
-Next chapter: [Filters](filters.md)
+Next chapter: [Overriding Default Order](default-order.md)
+

index.md

@@ -18,7 +18,8 @@
     2.  [Configuring Operations](core/operations.md#configuring-operations)
     3.  [Subresources](core/operations.md#subresources)
     4.  [Creating Custom Operations and Controllers](core/operations.md#creating-custom-operations-and-controllers)
-5.  [Filters](core/filters.md)
+5.  [Overriding Default Order](core/default-order.md)
+6.  [Filters](core/filters.md)
     1.  [Doctrine ORM Filters](core/filters.md#doctrine-orm-filters)
         1.  [Search Filter](core/filters.md#search-filter)
         2.  [Date Filter](core/filters.md#date-filter)
@@ -35,7 +36,7 @@
     3.  [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)
+7.  [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)
@@ -46,24 +47,24 @@
     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)
+8.  [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)
+9.  [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)
+10.  [The Event System](core/events.md)
+11. [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)
     4.  [Writing a Custom Normalizer](core/content-negotiation.md#writing-a-custom-normalizer)
-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)
+12. [Using External JSON-LD Vocabularies](core/external-vocabularies.md)
+13. [Extending JSON-LD context](core/extending-jsonld-context.md)
+14. [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)
-14. [Extensions](core/extensions.md)
+15. [Extensions](core/extensions.md)
     1.  [Custom Extension](core/extensions.md#custom-extension)
     2.  [Filter upon the current user](core/extensions.md#example)
 16. [Security](core/security.md)