tag documentation

nested entities transformer map in parent transformer
apiary helper factory fix for transformer setter
auth transformer fix

api/app/Http/Controllers/ArticleTagController.php

@@ -8,7 +8,7 @@
 
 namespace App\Http\Controllers;
 
-use App\Http\Transformers\EloquentModelTransformer;
+use App\Http\Transformers\ArticleTagTransformer;
 use App\Models\Article;
 use App\Models\BaseModel;
 use App\Models\Tag;
@@ -19,7 +19,7 @@ class ArticleTagController extends ChildEntityController
 {
     protected $relationName = 'tags';
 
-    public function __construct(Article $parentModel, EloquentModelTransformer $transformer)
+    public function __construct(Article $parentModel, ArticleTagTransformer $transformer)
     {
         parent::__construct($parentModel, $transformer);
     }

api/app/Http/Transformers/ArticleTagTransformer.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Created by PhpStorm.
+ * User: ivanmatveev
+ * Date: 21.08.15
+ * Time: 17:15
+ */
+
+namespace App\Http\Transformers;
+
+use App\Models\Tag;
+
+class ArticleTagTransformer extends EloquentModelTransformer
+{
+    public $addSelfKey = false;
+
+    /**
+     * @param $collection
+     * @return mixed
+     */
+    public function transformCollection($collection)
+    {
+        /** @var Tag[] $collection */
+        foreach ($collection as $item) {
+            $item->addHidden(['tag_id','pivot']);
+        }
+
+        return parent::transformCollection($collection);
+    }
+
+}

api/app/Http/Transformers/ArticleTransformer.php

@@ -12,6 +12,11 @@
 
 class ArticleTransformer extends EloquentModelTransformer
 {
+
+    public $nestedMap = [
+        'tags' => ArticleTagTransformer::class
+    ];
+
     /**
      * @param $collection
      * @return mixed

api/app/Http/Transformers/AuthTokenTransformer.php

@@ -11,10 +11,19 @@ class AuthTokenTransformer extends EloquentModelTransformer
     /**
      * Transform the token string into an response array.
      *
-     * @param  string  $token
+     * @param  string  $object
      * @return array
      */
-    public function transformItem($token)
+    public function transformItem($object)
+    {
+        if (is_string($object)){
+            return $this->transformToken($object);
+        }
+
+        return parent::transformItem($this->transformToken($object['token']));
+    }
+
+    protected function transformToken($token)
     {
         $token = new Token($token);
         $jwtAuth = App::make('Tymon\JWTAuth\JWTAuth');
@@ -25,6 +34,7 @@ public function transformItem($token)
         ];
     }
 
+
     /**
      * Collections are not used for token transformations.
      *
@@ -37,14 +47,4 @@ public function transformCollection($collection)
         throw new NotImplementedException('Collections are not used for tokens.');
     }
 
-    /**
-     * Transform the object into a response entity
-     * @param $object
-     * @return array
-     */
-    public function transform($object)
-    {
-        $thisTransformation = $this->transformItem($object['token']);
-        return parent::transform($thisTransformation);
-    }
 }

api/app/Http/Transformers/EloquentModelTransformer.php

@@ -13,11 +13,17 @@
 use Illuminate\Contracts\Support\Arrayable;
 use Spira\Model\Collection\Collection;
 use Spira\Model\Model\BaseModel;
+use Spira\Responder\Contract\TransformerInterface;
 use Traversable;
 
 class EloquentModelTransformer extends BaseTransformer
 {
     public static $badRoutes = [];
+
+    public $addSelfKey = true;
+
+    public $nestedMap = [];
+
     /**
      * Turn the object into a format adjusted array.
      *
@@ -66,7 +72,9 @@ public function transform($object)
         }
 
         if (($object instanceof BaseModel)) {
-            $array = $this->addSelfKey($object, $array);
+            if ($this->addSelfKey){
+                $array = $this->addSelfKey($object, $array);
+            }
 
             $array = $this->nestRelations($object, $array);
         }
@@ -186,13 +194,18 @@ protected function camelCase($str)
      */
     private function nestRelations($object, $array)
     {
+        /** @var BaseModel $object */
         if (count($object['relations']) > 0) {
             foreach ($object['relations'] as $relation => $childModelOrCollection) {
+                if (in_array($relation,$object->getHidden())){
+                    continue;
+                }
+                $transformer = $this->getTransformerForNested($relation);
                 $childTransformed = null;
                 if ($childModelOrCollection instanceof Collection) {
-                    $childTransformed = $this->transformCollection($childModelOrCollection);
+                    $childTransformed = $transformer->transformCollection($childModelOrCollection);
                 } else {
-                    $childTransformed = $this->transformItem($childModelOrCollection);
+                    $childTransformed = $transformer->transformItem($childModelOrCollection);
                 }
 
                 $array = $array + ['_' . $relation => $childTransformed];
@@ -202,4 +215,20 @@ private function nestRelations($object, $array)
 
         return $array;
     }
+
+    /**
+     * @param string $relationName
+     * @param string $default
+     * @return TransformerInterface
+     */
+    private function getTransformerForNested($relationName, $default = EloquentModelTransformer::class)
+    {
+        if (isset($this->nestedMap[$relationName])){
+            $className = $this->nestedMap[$relationName];
+        }else{
+            $className = $default;
+        }
+
+        return new $className($this->getService());
+    }
 }

api/app/Services/ModelFactoryInstance.php

@@ -244,8 +244,8 @@ public function transformed()
         if (!$this->transformer) {
             $this->transformer = new EloquentModelTransformer($this->transformerService);
         }
-
-        $transformedEntity = $this->transformerService->{$this->entityType}($entity, $this->transformer);
+        $method = 'transform'.ucfirst($this->entityType);
+        $transformedEntity = $this->transformer->{$method}($entity);
 
         $transformedEntity = array_except($transformedEntity, $this->hide); //allow the definer to specify transformed values to hide
 

api/resources/views/documentation/apiary.blade.apib

@@ -36,3 +36,4 @@ flexibility than the base laravel `factory()` methods.
 @include('documentation.sections.timezones')
 @include('documentation.sections.countries')
 @include('documentation.sections.article')
+@include('documentation.sections.tag')

api/resources/views/documentation/sections/article.blade.apib

@@ -26,7 +26,7 @@ Note that this route returns paginated results as defined in the `Content-Range`
 
             {!!
                 $factory->get(\App\Models\Article::class)
-                    ->hide(['content'])
+                    ->setTransformer(App\Http\Transformers\ArticleTransformer::class)
                     ->count(10)
                     ->json()
             !!}
@@ -146,3 +146,21 @@ Note that this route returns paginated results as defined in the `Content-Range`
 
 + Response 204
 
+## Article Tags [/articles/{articleId}/tags]
++ Parameters
+    + articleId (required, uuid, `{!! $faker->uuid !!}`) ... Unique `id` or `uri` of the article to perform action with.
+
+### Retrieve all article's tags data [GET]
+#### Restrictions
+* Allowed - [all]
+
++ Response 200 (application/json)
+    + Body
+
+            {!!
+                $factory->get(\App\Models\Tag::class)
+                    ->setTransformer(App\Http\Transformers\ArticleTagTransformer::class)
+                    ->count(3)
+                    ->json()
+            !!}
+

api/resources/views/documentation/sections/tag.blade.apib

@@ -0,0 +1,70 @@
+# Group Article Tags
+Tags are generic mechanism of tagging particular article and find articles having one and the same tag.
+
+## Tag Entity [/tags]
+
+### Create tag entity [POST]
+
+#### Restrictions
+* Allowed - [admin]
+
++ Request
+    + Body
+
+            {!!
+                $factory->get(\App\Models\Tag::class)
+                    ->hide(['_self'])
+                    ->json()
+            !!}
+
++ Request
+    + Body
+
+            {!!
+                $factory->get(\App\Models\Tag::class)
+                    ->showOnly(['_self'])
+                    ->json()
+            !!}
+
++ Response 201
+
+## Exiting Tag Entity Actions [/tags/{tagId}]
+
++ Parameters
+    + tagId (required, uuid, `{!! $faker->uuid !!}`) ... Unique `id` or `tag` of the tag to perform action with.
+
+
+### Retrieve a tag [GET]
+
+#### Restrictions
+* Allowed - [admin]
++ Response 200 (application/json)
+
+    + Body
+
+            {!! $factory->json(\App\Models\Tag::class) !!}
+
+### Update the tag [PATCH]
+
+#### Restrictions
+* Allowed - [admin]
+
++ Request
+    + Body
+
+            {!!
+                $factory->get(\App\Models\Tag::class)
+                    ->hide(['_self'])
+                    ->showOnly(['tag'])
+                    ->json()
+            !!}
+
+
++ Response 204
+
+
+### Delete the tag [DELETE]
+#### Restrictions
+* Allowed - [admin]
+
++ Response 204

api/tests/integration/ArticleTest.php

@@ -103,6 +103,21 @@ public function testGetOne()
         $this->assertTrue(is_string($object->permalink)||is_null($object->permalink));
     }
 
+    public function testGetOneWithNestedTags()
+    {
+        $entity = factory(Article::class)->create();
+        $tags = factory(\App\Models\Tag::class, 4)->create();
+        $entity->tags()->sync($tags->lists('tag_id')->toArray());
+
+        $this->get('/articles/'.$entity->article_id, ['with-nested'=> 'tags']);
+        $this->assertResponseOk();
+        $this->shouldReturnJson();
+
+        $object = json_decode($this->response->getContent());
+        $this->assertObjectHasAttribute('_tags', $object);
+        $this->assertEquals(4,count($object->_tags));
+    }
+
     public function testGetOneByFirstPermalink()
     {
         $entity = factory(Article::class)->create();