Merge pull request #1008 from amyavari/docs/select-include-fields

Docs: clarify selecting fields for included relations

Author: freekmurze

config/query-builder.php

@@ -62,12 +62,14 @@
     'convert_relation_names_to_snake_case_plural' => true,
 
     /*
-     * By default, the package expects relationship names to be snake case plural when using fields[relationship].
-     * For example, fetching the id and name for a userOwner relation would look like this:
-     * GET /users?fields[user_owner]=id,name
+     * This is an alternative to the previous option if you don't want to use default snake case plural for fields[relationship].
+     * It resolves the table name for the related model using the Laravel model class and, based on your chosen strategy,
+     * matches it with the fields[relationship] provided in the request.
      *
-     * Set this to one of `snake_case`, `camelCase` or `none` if you want to enable table name resolution in addition to the relation name resolution
-     * GET /users?include=topOrders&fields[orders]=id,name
+     * Set this to one of `snake_case`, `camelCase` or `none` if you want to enable table name resolution in addition to the relation name resolution.
+     * `snake_case` => Matches table names like 'topOrders' to `fields[top_orders]`
+     * `camelCase` => Matches table names like 'top_orders' to 'fields[topOrders]'
+     * `none` => Uses the exact table name
      */
     'convert_relation_table_name_strategy' => false,
 

docs/features/including-relationships.md

@@ -169,7 +169,7 @@ QueryBuilder::for(User::class)
 
 ## Selecting included fields
 
-You can select only some fields to be included using the [`allowedFields` method on the query builder](https://spatie.be/docs/laravel-query-builder/v5/features/selecting-fields/).
+You can select only some fields to be included using the [`allowedFields` method on the query builder](https://spatie.be/docs/laravel-query-builder/v6/features/selecting-fields/).
 
 ⚠️ `allowedFields` must be called before `allowedIncludes`. Otherwise the query builder wont know what fields to include for the requested includes and an exception will be thrown.
 

docs/features/selecting-fields.md

@@ -42,14 +42,15 @@ $users = QueryBuilder::for(User::class)
 Selecting fields for included models works the same way. This is especially useful when you only need a couple of columns from an included relationship. Consider the following example:
 
 ```php
-GET /posts?include=author&fields[author]=id,name
+GET /posts?include=author&fields[authors]=id,name
 
 QueryBuilder::for(Post::class)
-    ->allowedFields('author.id', 'author.name')
+    ->allowedFields('authors.id', 'authors.name')
     ->allowedIncludes('author');
 
 // All posts will be fetched including _only_ the name of the author. 
 ```
+⚠️ **Note:** In `allowedFields`, you must always use the _snake case plural_ of your relation name. If you want to change this behavior, you can change the settings in the [configuration file](https://spatie.be/docs/laravel-query-builder/v6/installation-setup)
 
 ⚠️ Keep in mind that the fields query will completely override the `SELECT` part of the query. This means that you'll need to manually specify any columns required for Eloquent relationships to work, in the above example `author.id`. See issue [#175](https://github.com/spatie/laravel-query-builder/issues/175) as well.
 

docs/installation-setup.md

@@ -12,6 +12,7 @@ composer require spatie/laravel-query-builder
 The package will automatically register its service provider.
 
 You can optionally publish the config file with:
+
 ```bash
 php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider" --tag="query-builder-config"
 ```
@@ -72,12 +73,33 @@ return [
     /*
      * By default, the package expects relationship names to be snake case plural when using fields[relationship].
      * For example, fetching the id and name for a userOwner relation would look like this:
-     * GET /users?fields[user_owner]=id,name
+     * GET /users?include=userOwner&fields[user_owners]=id,name
      *
      * Set this to `false` if you don't want that and keep the requested relationship names as-is and allows you to
      * request the fields using a camelCase relationship name:
-     * GET /users?fields[userOwner]=id,name
+     * GET /users?include=userOwner&fields[userOwner]=id,name
      */
     'convert_relation_names_to_snake_case_plural' => true,
+
+    /*
+     * This is an alternative to the previous option if you don't want to use default snake case plural for fields[relationship].
+     * It resolves the table name for the related model using the Laravel model class and, based on your chosen strategy,
+     * matches it with the fields[relationship] provided in the request.
+     *
+     * Set this to one of `snake_case`, `camelCase` or `none` if you want to enable table name resolution in addition to the relation name resolution.
+     * `snake_case` => Matches table names like 'topOrders' to `fields[top_orders]`
+     * `camelCase` => Matches table names like 'top_orders' to 'fields[topOrders]'
+     * `none` => Uses the exact table name
+     */
+    'convert_relation_table_name_strategy' => false,
+
+    /*
+     * By default, the package expects the field names to match the database names
+     * For example, fetching the field named firstName would look like this:
+     * GET /users?fields=firstName
+     *
+     * Set this to `true` if you want to convert the firstName into first_name for the underlying query
+     */
+    'convert_field_names_to_snake_case' => false,
 ];
 ```