From 3d28654cd04127d626a2d2a1cf33cecb0350bcdf Mon Sep 17 00:00:00 2001 From: qrazi Date: Thu, 25 May 2017 09:18:26 +0200 Subject: [PATCH 1/2] Add `includes` and `excludes` support to endpoint configuration --- README.md | 84 ++++++++++++++++++- .../controllers/ElementApiController.php | 8 ++ 2 files changed, 91 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 160cb66..621f532 100644 --- a/README.md +++ b/README.md @@ -171,7 +171,7 @@ The query string param name that should be used to identify which page is being Note that it cannot be set to `'p'` because that’s the parameter Craft uses to check the requested path. -### `resourceKey` +#### `resourceKey` The key that the elements should be nested under in the response data. By default this will be `'data'`. @@ -201,6 +201,88 @@ Possible values are: - `'jsonFeed'` – formats data based on [JSON Feed V1](https://jsonfeed.org/version/1) (see the [JSON Feed](#json-feed) example below). - A custom serializer instance. +#### `includes` + +The [transformers](http://fractal.thephpleague.com/transformers/) that should be included to transform nested entities in the returned data. +Includes need to be defined on the Transformer and will otherwise be ignore. The default Element API Transformer has no includes defined, this option will have to be used in tandem with your own Transformer-classes. + +Add it to the config of the endpoint. + +```php +'includes' => [ + 'images', +] +``` + +And create your own Transformer. + +```php +final class SomeTransformer extends TransformerAbstract +{ + /** + * @var array + */ + protected $availableIncludes = [ + 'images', + ]; + + /** + * @param EntryModel $entry + * + * @return array + */ + public function transform(EntryModel $entry) + { + ... + } + + /** + * @param EntryModel $entry + * + * @return \League\Fractal\Resource\Collection + */ + public function includeImages(EntryModel $entry) + { + $images = $entry->entry_images_field->find(); + + return $this->collection( + $images, + new ImageTransformer() + ); + } +} + +``` + +#### `excludes` + +Similar to including nested Transformers also allow to exclude nested data. This is mainly convenient when a default include is defined in a Transformer and for a specific endpoint you don not want that include. Have a look at the [documentation](http://fractal.thephpleague.com/transformers/) for more details. + +Assuming a Transformer with a default include. + +```php +final class SomeTransformer extends TransformerAbstract +{ + /** + * @var array + */ + protected $defaultIncludes = [ + 'images', + ]; + + ... +} + +``` + +Add the exclude to the config of the endpoint. + +```php +'excludes' => [ + 'images', +] +``` + #### `jsonOptions` The value of the `$options` argument that will be passed to [`json_encode()`](http://php.net/manual/en/function.json-encode.php) when preparing the response. By default no options will be passed. diff --git a/elementapi/controllers/ElementApiController.php b/elementapi/controllers/ElementApiController.php index 7d166a1..c0a6fa9 100644 --- a/elementapi/controllers/ElementApiController.php +++ b/elementapi/controllers/ElementApiController.php @@ -114,6 +114,14 @@ public function actionGetElements($configFactory = null, array $config = null) } $fractal->setSerializer($serializer); + // Set the includes + $includes = isset($config['includes']) ? $config['includes'] : []; + $fractal->parseIncludes($includes); + + // Set the excludes + $excludes = isset($config['excludes']) ? $config['excludes'] : []; + $fractal->parseExcludes($excludes); + // Define the transformer if (is_callable($config['transformer']) || $config['transformer'] instanceof TransformerAbstract) { From 61098eae5e504afd7069cde548f727de77a819bb Mon Sep 17 00:00:00 2001 From: Brandon Kelly Date: Thu, 25 May 2017 04:52:24 -0700 Subject: [PATCH 2/2] Readme cleanup --- README.md | 76 +++++++++++++------------------------------------------ 1 file changed, 17 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 621f532..68bb66d 100644 --- a/README.md +++ b/README.md @@ -203,85 +203,43 @@ Possible values are: #### `includes` -The [transformers](http://fractal.thephpleague.com/transformers/) that should be included to transform nested entities in the returned data. -Includes need to be defined on the Transformer and will otherwise be ignore. The default Element API Transformer has no includes defined, this option will have to be used in tandem with your own Transformer-classes. - -Add it to the config of the endpoint. +The [include names](http://fractal.thephpleague.com/transformers/#including-data) that should be included for the current request, if any. ```php -'includes' => [ - 'images', -] +'includes' => craft()->request->getQuery('include'), ``` -And create your own Transformer. +Note that this setting requires a custom transformer class that’s prepped to handle includes: ```php -final class SomeTransformer extends TransformerAbstract +class MyTransformerClassName extends TransformerAbstract { - /** - * @var array - */ - protected $availableIncludes = [ - 'images', - ]; - - /** - * @param EntryModel $entry - * - * @return array - */ - public function transform(EntryModel $entry) + protected $availableIncludes = ['author']; + + public function includeAuthor(EntryModel $entry) { - ... + return $this->item($entry->author, function(UserModel($author) { + return [ + 'id' => $author->id, + 'name' => $author->name, + ]; + }); } - /** - * @param EntryModel $entry - * - * @return \League\Fractal\Resource\Collection - */ - public function includeImages(EntryModel $entry) - { - $images = $entry->entry_images_field->find(); - - return $this->collection( - $images, - new ImageTransformer() - ); - } + // ... } - ``` #### `excludes` -Similar to including nested Transformers also allow to exclude nested data. This is mainly convenient when a default include is defined in a Transformer and for a specific endpoint you don not want that include. Have a look at the [documentation](http://fractal.thephpleague.com/transformers/) for more details. -Assuming a Transformer with a default include. +The [include names](http://fractal.thephpleague.com/transformers/#including-data) that should be excluded for the current request, which would otherwise have been included (e.g. if they were listed as a default include), if any. ```php -final class SomeTransformer extends TransformerAbstract -{ - /** - * @var array - */ - protected $defaultIncludes = [ - 'images', - ]; - - ... -} - +'excludes' => 'author', ``` -Add the exclude to the config of the endpoint. - -```php -'excludes' => [ - 'images', -] -``` +Like [`includes`](#includes), this setting requires a custom transformer class. #### `jsonOptions`