jeffersonsimaogoncalves/cakephp-fractal-transformer-view

CakePHP view builder utilizing Fractal library for entities transformation

2.0.0 2020-11-09 13:16 UTC

This package is auto-updated.

Last update: 2022-05-14 21:35:06 UTC


README

This plugin is a thin wrapper for JsonView that allows using Fractal transformers for your API output. What is Fractal?

Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON. Think of this as a view layer for your JSON/YAML/etc. When building an API it is common for people to just grab stuff from the database and pass it to json_encode(). This might be passable for “trivial” APIs but if they are in use by the public, or used by mobile applications then this will quickly lead to inconsistent output.

Requirements

  • CakePHP 3.6+

Installation

You can install this plugin into your CakePHP application using Composer.

composer require jeffersonsimaogoncalves/cakephp-fractal-transformer-view

Usage

To enable the plugin set FractalTransformerView.FractalTransformer class name for viewBuilder. Then you just do what you would normally do in your data views - specify which view vars you want to get serialized by setting _serialize var. E.g.:

namespace App\Controller;

class ArticlesController extends AppController
{
    public function initialize()
    {
        parent::initialize();
        $this->loadComponent('RequestHandler');
        
        $this->viewBuilder()->className('FractalTransformerView.FractalTransformer');
    }

    public function index()
    {
        // Set the view vars that have to be serialized.
        $this->set('articles', $this->paginate());
        // Specify which view vars JsonView should serialize.
        $this->set('_serialize', ['articles']);
    }
}

The view will look for transformer class starting with entity name. E.g.:

namespace App\Model\Transformer;

use App\Model\Entity\Article;
use League\Fractal\TransformerAbstract;

class ArticleTransformer extends TransformerAbstract
{
    /**
     * Creates a response item for each instance
     *
     * @param Article $article post entity
     * @return array transformed post
     */
    public function transform(Article $article)
    {
        return [
            'title' => $article->get('title')
        ];
    }
}

If transformer class not found the variable is serialized the normal way.

Custom transformer class name can be set by defining _transformer view var:

$this->set('_transform', ['articles' => '\App\Model\Transformer\CustomArticleTransformer']);

You can also define if you don't want to use transformer for certain variables:

$this->set('_transform', ['articles' => false]);

Bugs & Feedback

https://github.com/jeffersonsimaogoncalves/cakephp-fractal-transformer-view/issues

Credits

This work is based on the code by Andrej Griniuk.