README

Presentit is an easy to use tool for custom presentations of nested data structures that are used in API responses.

Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'name' => $user->first_name . " " . $user->last_name,
        'image' => $user->image ?: Present::hidden(),
        'friends' => Present::each($user->friends)->with(function (User $friend) {
            return [
                //...
            ]
        })
    ];
})->show();

Features

Fluent interface to transform nested data structures
Transformer classes for presentation logic code reuse.
Callback transformers for inline data transformations.
Control data properties visibility using the Hidden object instead of using if statements.

Adapters

Laravel framework adapter

Docs

Installation
Basic usage

Installation

Install using composer

composer require dan-har/presentit

Basic usage

The Present class is used for transforming single resource or a collection of resources.

Present a single resource by using the item() method.

$presentation = Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        // ...
    ];
});

Present a list of resources using the collection or each methods. Each of the items in the list will be transformed using the transformer that is passed to the each method.

$presentation = Present::collection($usersList)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        // ...
    ];
});

The with function excepts a Transformer and returns a Presentation object. To get the presentation data as array use the show method.

$array = $presentation->show();

Commonly usage of the Presentation is with an http response object. Usage example with Symphony JsonResponse

$response = new JsonResponse($presentation->show());

$response->send();

Hide keys using the Hidden object.

$presentation = Present::item($user)->with(function (User $user) {
    return [
        'id' => $user->id,
        'first_name' => ucfirst($user->first_name),
        'birthday' => $user->isBirthDayPublic() ? $user->birthday : Present::hidden() // or use Hidden::key()
        // ...
    ];
});

When a value in an array data structure is a Hidden type the key will not be presented. The above example presentation will be

$array = $presentation->show();

// if birthday is not public ->
// $array = [
//     'id' => $user->id,
//     'first_name' => ucfirst($user->first_name),
// ]
// birthday key is not visible.

The with method accepts a transformer. A transformer can be a callable, Transformer instance or a transformer class string name.

Using a Transformer class name string

class UserTransformer 
{
    public function transform(User $user) 
    {
        return [
            'id' => $user->id,
            'first_name' => ucfirst($user->first_name),
            // ...
        ];
    } 
}

$presentation = Present::each($usersList)->with(UserTransformer::class);

Or with Transformer instance

$tranformer = new UserTransformer();

$presentation = Present::item($user)->with($transformer);
$presentation = Present::each($usersList)->with($transformer);

Nested presentation using a Transformer class

use Presentit\Present;

class UserTransformer 
{
    public function transform(User $user) 
    {
        return [
            'id' => $user->id,
            'first_name' => ucfirst($user->first_name),
            'friends' => $user->friends ? Present::each($user->friends)->with(UserTransformer::class) : [],
            // ...
        ];
    } 
}

$presentation = Present::each($usersList)->with(UserTransformer::class);

dan-har / presentit

Maintainers

Details