Add Lists documentation

Author: Julien Neuhart

docs/docs/11_Lists/1_Overview.md

@@ -1,6 +1,15 @@
 ---
 title: Overview
-slug: /theme
+slug: /lists
 ---
 
-🚧
+In the API, a list means retrieving data from the database according to:
+
+* Random filters (e.g., free search).
+* Predictable filters (e.g., enum values).
+* A sort direction on a field.
+* A limit and an offset.
+
+On the web application, a list means displaying data according to user's inputs.
+
+In the next chapters, we explain how it works and how you should implement it.

docs/docs/11_Lists/2_Database.md

@@ -0,0 +1,78 @@
+---
+title: Database
+slug: /lists/database
+---
+
+## DAO
+
+The first step is to write a query in a DAO class. For instance:
+
+```php title="src/api/src/Domain/Dao/UserDao.php"
+/**
+ * @return User[]|ResultIterator
+ */
+public function search(
+    ?string $search = null,
+    ?Role $role = null,
+    ?UsersSortBy $sortBy = null,
+    ?SortOrder $sortOrder = null
+): ResultIterator {
+    $sortBy    = $sortBy ?: UsersSortBy::FIRST_NAME();
+    $sortOrder = $sortOrder ?: SortOrder::ASC();
+
+    return $this->find(
+        [
+            'first_name LIKE :search OR last_name LIKE :search OR email LIKE :search',
+            'role = :role',
+        ],
+        [
+            'search' => '%' . $search . '%',
+            'role' => $role,
+        ],
+        $sortBy . ' ' . $sortOrder
+    );
+}
+```
+
+Here we have:
+
+* A random filter, the `$search` string.
+* A predictable filter, the `$role` enum.
+* A sort direction and a sort column.
+
+All the arguments are optional (`= null`).
+
+:::note
+
+📣  If a parameter's value is `null`, [TDBM](https://github.com/thecodingmachine/tdbm)
+automatically removes the corresponding conditions in the first argument of the `find` method.
+
+:::
+
+## ResultIterator
+
+Thanks to the `ResultIterator` class, you may retrieve a precise scope of the resulting data:
+
+```php
+$result = $userDao->search();
+$result->take($offset, $limit);
+```
+
+:::note
+
+📣  Most of the time, you won't have to explicitly call the `take` method 
+thanks to [GraphQLite](https://graphqlite.thecodingmachine.io/). More on that in the next chapter.
+
+:::
+
+## Enum
+
+The folder *src/api/src/Domain/Enum* contains our enums.
+
+Each enum's key (i.e., `FIRST_NAME`) is a GraphQL value, while each enum's value (i.e., `first_name`)
+is a valid SQL expression.
+
+Most enums are for:
+
+* Sort by values.
+* Business data.

docs/docs/11_Lists/3_GraphQL.md

@@ -0,0 +1,57 @@
+---
+title: GraphQL
+slug: /lists/graphql
+---
+
+In the previous chapter, we define a `search` method in a DAO.
+
+We now have to create a GraphQL query from it:
+
+```php title="src/api/src/UseCase/User/GetUsers.php"
+/**
+ * @return User[]|ResultIterator
+ *
+ * @Query
+ * @Logged
+ * @Security("is_granted('ROLE_ADMINISTRATOR')")
+ */
+public function users(
+    ?string $search = null,
+    ?Role $role = null,
+    ?UsersSortBy $sortBy = null,
+    ?SortOrder $sortOrder = null
+): ResultIterator {
+    return $this->userDao->search(
+        $search,
+        $role,
+        $sortBy,
+        $sortOrder
+    );
+}
+```
+
+It's simple as that! 😉
+
+Let's take a look at the GraphQL query for the `GetUsers` use case:
+
+```graphql title="GraphQL query"
+query users($search: String, $role: Role, $sortBy: UsersSortBy, $sortOrder: SortOrder, $limit: Int!, $offset: Int!) {
+  users(search: $search, role: $role, sortBy: $sortBy, sortOrder: $sortOrder) {
+    items(limit: $limit, offset: $offset) {
+      id
+      firstName
+      lastName
+      email
+      locale
+      role
+    }
+    count
+  }
+}
+```
+
+Here we can see that:
+
+1. The enums are valid GraphQL types.
+2. The `items` property with the `limit` and `offset` arguments plus the `count` property come from the `ResultIterator`.
+