add support for includes

Author: freekmurze

README.md

@@ -171,6 +171,29 @@ fractal()
 You can change the default serializer by providing the classname of your favorite serializer in
 the config file.
 
+### Using includes
+
+Fractal provides support for [optionally including data](http://fractal.thephpleague.com/transformers/) on the relationships for
+the data you're exporting. You can use Fractal's `parseInclude` which accepts a string or an array:
+
+```php
+$resultWithParseCharacters = fractal()
+    ->collection($this->testBooks, new TestTransformer())
+    ->parseIncludes(['characters', 'publisher'])
+    ->toArray();
+```
+
+To improve readablity you can also a function named `include` followed by the name
+of the include you want to... include:
+
+```php
+$resultWithParseCharacters = fractal()
+    ->collection($this->testBooks, new TestTransformer())
+    ->includeCharacters()
+    ->includePublisher()
+    ->toArray();
+```
+
 ## Change log
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

src/Fractal.php

@@ -24,6 +24,11 @@ class Fractal
      */
     protected $transformer;
 
+    /**
+     * @var array
+     */
+    protected $includes = [];
+
     /**
      * @var string
      */
@@ -104,6 +109,40 @@ public function transformWith($transformer)
         return $this;
     }
 
+    /**
+     * Specify the includes
+     *
+     * @param array|string $includes Array or csv string of resources to include
+     *
+     * @return $this
+     */
+    public function parseIncludes($includes)
+    {
+        if (is_string($includes)) {
+            $includes = [$includes];
+        }
+
+        $this->includes = array_merge($this->includes, $includes);
+
+        return $this;
+    }
+
+    /**
+     * Support for magic methods to included data.
+     *
+     * @return $this
+     */
+    public function __call($name, array $arguments)
+    {
+        if (! starts_with($name, 'include')) {
+            trigger_error('Call to undefined method '.__CLASS__.'::'.$methodName.'()', E_USER_ERROR);
+        }
+
+        $includeName = lcfirst(substr($name, strlen('include')));
+
+        return $this->parseIncludes($includeName);
+    }
+
     /**
      * Set the serializer to be used.
      *
@@ -158,6 +197,10 @@ protected function transform($conversionMethod)
             $this->manager->setSerializer($this->serializer);
         }
 
+        if (!is_null($this->includes)) {
+            $this->manager->parseIncludes($this->includes);
+        }
+
         $resource = $this->getResource();
 
         $fractalData = $this->manager->createData($resource);

tests/Integration/IncludesTest.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Spatie\Fractal\Test\Integration;
+
+class IncludesTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function it_can_parse_includes()
+    {
+        $array = $this->fractal
+            ->collection($this->testBooks, new TestTransformer())
+            ->parseIncludes('characters')
+            ->toArray();
+
+        $expectedArray = ['data' => [
+            ['id' => 1, 'author' => 'Philip K Dick',  'characters' => ['data' => ['Death', 'Hex']]],
+            ['id' => 2, 'author' => 'George R. R. Satan', 'characters' => ['data' => ['Ned Stark', 'Tywin Lannister']]],
+        ]];
+
+        $this->assertEquals($expectedArray, $array);
+    }
+
+    /**
+     * @test
+     */
+    public function it_provides_a_convenience_method_to_include_includes()
+    {
+        $resultWithParseIncludes = fractal()
+            ->collection($this->testBooks, new TestTransformer())
+            ->parseIncludes('characters')
+            ->toArray();
+
+        $resultWithParseCharacters = fractal()
+            ->collection($this->testBooks, new TestTransformer())
+            ->includeCharacters()
+            ->toArray();
+
+        $this->assertEquals($resultWithParseIncludes, $resultWithParseCharacters);
+    }
+
+    /**
+     * @test
+     */
+    public function it_can_handle_multiple_includes()
+    {
+        $array = $this->fractal
+            ->collection($this->testBooks, new TestTransformer())
+            ->includeCharacters()
+            ->includePublisher()
+            ->toArray();
+
+        $expectedArray = ['data' => [
+            ['id' => 1, 'author' => 'Philip K Dick',  'characters' => ['data' => ['Death', 'Hex']], 'publisher' => ['data' => ['Elephant books']]],
+            ['id' => 2, 'author' => 'George R. R. Satan', 'characters' => ['data' => ['Ned Stark', 'Tywin Lannister']], 'publisher' => ['data' => ['Bloody Fantasy inc.']]],
+        ]];
+
+        $this->assertEquals($expectedArray, $array);
+    }
+}

tests/Integration/TestCase.php

@@ -38,13 +38,17 @@ public function setUp($defaultSerializer = '')
                 'yr' => '1998',
                 'author_name' => 'Philip K Dick',
                 'author_email' => '[email protected]',
+                'characters' => [['name' => 'Death'], ['name' => 'Hex']],
+                'publisher' => 'Elephant books',
             ],
             [
                 'id' => '2',
                 'title' => 'Game Of Kill Everyone',
                 'yr' => '2014',
                 'author_name' => 'George R. R. Satan',
                 'author_email' => '[email protected]',
+                'characters' => [['name' => 'Ned Stark'], ['name' => 'Tywin Lannister']],
+                'publisher' => 'Bloody Fantasy inc.',
             ],
         ];
     }

tests/Integration/TestTransformer.php

@@ -6,6 +6,16 @@
 
 class TestTransformer extends TransformerAbstract
 {
+    /**
+     * List of resources possible to include.
+     *
+     * @var array
+     */
+    protected $availableIncludes = [
+        'characters',
+        'publisher',
+    ];
+
     /**
      * @param array $book
      *
@@ -18,4 +28,36 @@ public function transform(array $book)
             'author' => $book['author_name'],
         ];
     }
+
+    /**
+     * Include characters.
+     *
+     * @param array $book
+     *
+     * @return \League\Fractal\ItemResource
+     */
+    public function includeCharacters(array $book)
+    {
+        $characters = $book['characters'];
+
+        return $this->collection($characters, function ($character) {
+            return $character['name'];
+        });
+    }
+
+    /**
+     * Include characters.
+     *
+     * @param array $book
+     *
+     * @return \League\Fractal\ItemResource
+     */
+    public function includePublisher(array $book)
+    {
+        $publisher = $book['publisher'];
+
+        return $this->item([$publisher], function ($publisher) {
+            return $publisher;
+        });
+    }
 }