README

FractalTransformerView plugin for CakePHP

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 5.x (use ~1.0 for CakePHP 3.x, ~2.0 for CakePHP 4.x)

Installation

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

composer require andrej-griniuk/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 view builder option. E.g.:

namespace App\Controller;

class ArticlesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        
        $this->loadComponent('RequestHandler');
        
        $this->viewBuilder()->setClassName('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->viewBuilder()->setOption('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 builder option:

$this->viewBuilder()->setOption('transform', ['articles' => '\App\Model\Transformer\CustomArticleTransformer']);

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

$this->viewBuilder()->setOption('transform', ['articles' => false]);

You can set a custom serializer (class name or object) via serializer view builder option:

$this->viewBuilder()->setOption('serializer', new CustomSerializer());

Baking Transformers

To bake transformers you must include the plugin in your src/Application.php file. Add the following to your bootstrap method:

$this->addPlugin('FractalTransformerView');

You must also have the cakephp/bake composer package installed.

You can now run bin/cake bake transformer YOUR_MODEL to create transformers.

Bugs & Feedback

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

Credits

Inspired by @josegonzalez Using Fractal to transform entities for custom api endpoints.

License

Copyright (c) 2016, Andrej Griniuk and licensed under The MIT License.