CakePHP view builder utilizing Fractal library for entities transformation

3.0 2023-12-11 04:47 UTC

This package is auto-updated.

Last update: 2024-02-11 05:23:19 UTC


Build Status codecov License

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.


  • CakePHP 5.x (use ~1.0 for CakePHP 3.x, ~2.0 for CakePHP 4.x)


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

composer require andrej-griniuk/cakephp-fractal-transformer-view


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

    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:


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


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


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