diff --git a/config/query-builder.php b/config/query-builder.php index 94fca196..52604504 100644 --- a/config/query-builder.php +++ b/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, diff --git a/docs/features/including-relationships.md b/docs/features/including-relationships.md index 6c82f5ee..cead42f3 100644 --- a/docs/features/including-relationships.md +++ b/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. diff --git a/docs/features/selecting-fields.md b/docs/features/selecting-fields.md index b613e719..d7c82c3a 100644 --- a/docs/features/selecting-fields.md +++ b/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. diff --git a/docs/installation-setup.md b/docs/installation-setup.md index 557002b2..bbe5c763 100644 --- a/docs/installation-setup.md +++ b/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, ]; ```