PHPackages                             area17/twill-transformers - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. area17/twill-transformers

ActiveLibrary[Utility & Helpers](/categories/utility)

area17/twill-transformers
=========================

Transformers for Twill apps

v1.2.1(3y ago)1112.7k↓34.4%7[1 PRs](https://github.com/area17/twill-transformers/pulls)MITPHPPHP >=7.2

Since Aug 17Pushed 3y ago3 watchersCompare

[ Source](https://github.com/area17/twill-transformers)[ Packagist](https://packagist.org/packages/area17/twill-transformers)[ Docs](https://github.com/area17/twill-transformers)[ RSS](/packages/area17-twill-transformers/feed)WikiDiscussions unstable Synced 1mo ago

READMEChangelogDependencies (2)Versions (54)Used By (0)

Twill Transformers
==================

[](#twill-transformers)

[![Latest Version on Packagist](https://camo.githubusercontent.com/607b51506053dadac89e0fe8c3ac78b5f9ca15c00a7adbba43fcbd29e54cebd9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6172656131372f7477696c6c2d7472616e73666f726d6572732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/area17/twill-transformers)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Build Status](https://camo.githubusercontent.com/137cc90d175b84e65cef1abb84ffcf67264d7dc08bdf146876e29350b432dce4/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6172656131372f7477696c6c2d7472616e73666f726d6572732f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/area17/twill-transformers)[![Coverage Status](https://camo.githubusercontent.com/92ac3b66f7c5c9cf377f0625d58c4d6811102595a1a99daeede6c87dd4c0d6d8/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f6172656131372f7477696c6c2d7472616e73666f726d6572732e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/area17/twill-transformers/code-structure)[![Quality Score](https://camo.githubusercontent.com/889ac30632bc7172393fd678b4329de42804e72c54d66eded4e7980b970b0db0/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6172656131372f7477696c6c2d7472616e73666f726d6572732e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/area17/twill-transformers)[![Total Downloads](https://camo.githubusercontent.com/87fd0454c3143173ecc915c46a93bd04b4e8a5ab6f0437913e747ca89f1a884c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6172656131372f7477696c6c2d7472616e73666f726d6572732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/area17/twill-transformers)

This package allows you to create transformers to generate view data for your Twill app. It contains a base Transformer class and a series of traits, allowing you not only to transform model data, but also generate all blocks, from Twill's block editor and preview data.

Reasoning
---------

[](#reasoning)

The main class of this package was extracted from the work we did for a client where we decided to use Storybook and Twig templates to build the front end. The idea is to free the back end developer from writing front-end code. For this to happen, the whole data generation is automated, starting from the controller `view()` call.

Install
-------

[](#install)

### Via Composer

[](#via-composer)

```
composer require area17/twill-transformers
```

### Publish the config file

[](#publish-the-config-file)

```
php artisan vendor:publish --provider="A17\TwillTransformers\ServiceProvider"
```

Usage
-----

[](#usage)

For those using the same approach (Storybook + Twig), this is what you have to do to make it all happen:

### Create your base Transformer

[](#create-your-base-transformer)

Extend the class Transformer and create your basic page structure. All JSON generated by the transformer will have this structure.

```
namespace App\Transformers;

use A17\TwillTransformers\Transformer as TwillTransformer;

abstract class Transformer extends TwillTransformer
{
    /**
     * @return array|null
     */
    public function transform()
    {
        return $this->sanitize([
            'template_name' => $this->makeTemplateName(),

            'header' => $this->transformHeader($this->data),

            $this->makePageKey() => $this->transformData($this->data),

            'seo' => $this->transformSeo($this->data),

            'footer' => $this->transformFooter($this->data),
        ]);
    }
}
```

### Use required traits

[](#use-required-traits)

Add and use this one on your base controller:

```
use A17\TwillTransformers\ControllerTrait;
```

And this one on your base repository:

```
use A17\TwillTransformers\RepositoryTrait;
```

### Create your first Transformer

[](#create-your-first-transformer)

Note that data to be transformed is self-contained inside the transformer object. So `$this` holds everything it's responsible for transforming, and as it's usually a Laravel Model descendent, it also has access to everything we usually do with models, accessors, mutators, relationships, presenters, everything.

```
namespace App\Transformers;

class LandingPage extends Transformer
{
    public function transform()
    {
        return [
            'hero' => [
                'title' => $this->title,

                'text' => $this->text,

                'image' => $this->transformMedia(),
            ],

            'blocks' => $this->transformBlocks(),

            'related' => $this->transformRelatedArticles(),
        ];
    }
}
```

### Create block transformers

[](#create-block-transformers)

Note that this is only required if your blocks are not compatible with the FE data needs. In order to reuse Twill blocks, BE and FE must agree on the structure and naming of all blocks. But, if you still have data transformation to be done on a block, you can create blocks as this:

```
namespace App\Transformers\Block;

use App\Transformers\Block;

class ArtistPortrait extends Block
{
    public function transform()
    {
        return [
            'component' => 'portrait',

            'data' => [
                'name' => $this->name,

                'text' => $this->main_info,

                'button' => [
                    'more_label' => ___('Lire plus'),
                    'less_label' => ___('Lire moins'),
                ],

                'extra_text' => $this->additional_info,

                'image' => $this->transformMedia(),
            ],
        ];
    }
}
```

### Reuse blocks as components

[](#reuse-blocks-as-components)

If you have a block transformer and needs to reuse it to generate data on your App transformers, or even other block transformers, you can basically call them this way:

```
public function transformArtistPortraits($portraits)
{
    return collect($portraits)->map(function ($portrait) {
        return $this->transformBlockArtistPortrait($portrait);
    });
}
```

If the `transform` method call starts with `Block`, like in `transformBlockArtistPortrait()`, it basically will try to instantiate the named block transformer class to be used.

This is the code for the block being called above:

```
namespace App\Transformers\Block;

use App\Transformers\Block;

class ArtistPortrait extends Block
{
    public function transform()
    {
        return [
            'component' => 'portrait',

            'data' => [
                'name' => $this->name,

                'text' => $this->main_info,

                'button' => [
                    'more_label' => ___('Lire plus'),
                    'less_label' => ___('Lire moins'),
                ],

                'extra_text' => $this->additional_info,

                'image' => $this->transformMedia(),
            ],
        ];
    }
}
```

Note that the data (a model, an array, an object) passed to your transformer (block or app transformer) can be accessed using `$this` from inside your block:

So, when we call a transformer like this:

```
$this->transformBlockArtistPortrait($portrait);
```

Inside the transformer, we can render images just by doing:

```
$this->transformMedia()
```

Or get the name of a portrait person this way:

```
$this->name
```

### Rendering the front-end

[](#rendering-the-front-end)

This is all you have to do to send JSON data to your front-end:

```
@extends('front.layouts.app')

@section('contents')
    @include("templates.{$template_name}")
@endsection
```

And if you need to take a look at the generated data, you just have to add `?output=json` the URL.

### Rendering previews on Twill

[](#rendering-previews-on-twill)

Previews are included, they are basically a `side effect` of this new approach, so you just have to configure your preview path on `twill.php` file:

```
'views_path' => 'admin._site.front',
```

And create this Blade template to your render previews for everything:

```
@extends('front.layouts.app')

@php
    $data = _transform($item);
@endphp

@section('contents')
    @include("templates.{$data['template_name']}", $data)
@endsection
```

### Twill's block editor

[](#twills-block-editor)

First, you need to have a block component for every block you render, even if it's only extending a base component from your app.

Then you just need to create this view, that will handle and render all blocks in the editor:

```
@php
    $transformed = _transform($block);

    $type = Str::kebab(Str::camel($transformed['type']));
@endphp

@include("components.block.{$type}.block-{$type}", $transformed)
```

Blade Transformers
------------------

[](#blade-transformers)

You can define the transformer directly inside a Blade template:

```
@extends('layouts.app')

@transformer(\App\Transformers\Post)

...
```

On your base Transformer add a `blade()` static radmethod to handle the data transformation:

```
public static function blade($transformer, $data): array
{
    if (app()->bound(BladeTransformer::class)) {
        return app(BladeTransformer::class)->transform($transformer, $data);
    }

    return [];
}
```

Then on each Transformer called from Blade, you can define a `transformStorybookData()` method to render fake data in case there is no data to be transformed available. This can be used, for instance, when rendering Storybook stories via [Blast](https://github.com/area17/blast).

```