Laravel 5 JSend Transformer Package

Compatible with Laravel 5.0, 5.1 & 5.2

Installation

Use Composer to install the package:

$ composer require nilportugues/laravel5-jsend

Laravel 5 / Lumen Configuration

Step 1: Add the Service Provider

Laravel

Open up config/app.php and add the following line under providers array:

'providers' => [

    //...
    \NilPortugues\Laravel5\JSend\Laravel5JSendServiceProvider::class,
],

Lumen

Open up bootstrap/app.phpand add the following lines before the return $app; statement:

$app->register(\NilPortugues\Laravel5\JSend\Laravel5JSendServiceProvider::class);
$app->configure('jsend');

Also, enable Facades by uncommenting:

$app->withFacades();

Step 2: Add the mapping

Create a jsend.php file in config/ directory. This file should return an array returning all the class mappings.

Step 3: Usage

For instance, lets say the following object has been fetched from a Repository , lets say PostRepository - this being implemented in Eloquent or whatever your flavour is:

use Acme\Domain\Dummy\Post;
use Acme\Domain\Dummy\ValueObject\PostId;
use Acme\Domain\Dummy\User;
use Acme\Domain\Dummy\ValueObject\UserId;
use Acme\Domain\Dummy\Comment;
use Acme\Domain\Dummy\ValueObject\CommentId;

//$postId = 9;
//PostRepository::findById($postId); 

$post = new Post(
  new PostId(9),
  'Hello World',
  'Your first post',
  new User(
      new UserId(1),
      'Post Author'
  ),
  [
      new Comment(
          new CommentId(1000),
          'Have no fear, sers, your king is safe.',
          new User(new UserId(2), 'Barristan Selmy'),
          [
              'created_at' => (new \DateTime('2015/07/18 12:13:00'))->format('c'),
              'accepted_at' => (new \DateTime('2015/07/19 00:00:00'))->format('c'),
          ]
      ),
  ]
);

And a series of mappings, placed in config/jsend.php, that require to use named routes so we can use the route() helper function:

<?php
//config/jsend.php
return [
    [
        'class' => 'Acme\Domain\Dummy\Post',
        'alias' => 'Message',
        'aliased_properties' => [
            'author' => 'author',
            'title' => 'headline',
            'content' => 'body',
        ],
        'hide_properties' => [

        ],
        'id_properties' => [
            'postId',
        ],
        'urls' => [
            'self' => ['name' => 'get_post'], //named route
            'comments' => ['name' => 'get_post_comments'], //named route
        ],
    ],
    [
        'class' => 'Acme\Domain\Dummy\ValueObject\PostId',
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'postId',
        ],
        'urls' => [
            'self' => ['name' => 'get_post'], //named route
        ],
    ],
    [
        'class' => 'Acme\Domain\Dummy\User',
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'userId',
        ],
        'urls' => [
            'self' => ['name' => 'get_user'], //named route
            'friends' => ['name' => 'get_user_friends'], //named route
            'comments' => ['name' => 'get_user_comments'], //named route
        ],
    ],
    [
        'class' => 'Acme\Domain\Dummy\ValueObject\UserId',
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'userId',
        ],
        'urls' => [
            'self' => ['name' => 'get_user'], //named route
            'friends' => ['name' => 'get_user_friends'], //named route
            'comments' => ['name' => 'get_user_comments'], //named route
        ],
    ],
    [
        'class' => 'Acme\Domain\Dummy\Comment',
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'commentId',
        ],
        'urls' => [
            'self' => ['name' => 'get_comment'], //named route
        ],
    ],
    [
        'class' => 'Acme\Domain\Dummy\ValueObject\CommentId',
        'alias' => '',
        'aliased_properties' => [],
        'hide_properties' => [],
        'id_properties' => [
            'commentId',
        ],
        'urls' => [
            'self' => ['name' => get_comment'], //named route
        ],
    ],
];

The named routes belong to the app/Http/routes.php. Here's a sample for the routes provided mapping:

Laravel

Route::get(
  '/post/{postId}',
  ['as' => 'get_post', 'uses' => 'PostController@getPostAction']
);

Route::get(
  '/post/{postId}/comments',
  ['as' => 'get_post_comments', 'uses' => 'CommentsController@getPostCommentsAction']
);

//...

Lumen

$app->get(
  '/post/{postId}',
  ['as' => 'get_post', 'uses' => 'PostController@getPostAction']
);

$app->get(
  '/post/{postId}/comments',
  ['as' => 'get_post_comments', 'uses' => 'CommentsController@getPostCommentsAction']
);

//...

All of this set up allows you to easily use the JSendSerializer service as follows:

<?php

namespace App\Http\Controllers;

use Acme\Domain\Dummy\PostRepository;
use NilPortugues\Laravel5\JSend\JSendSerializer;
use NilPortugues\Laravel5\JSend\JSendResponseTrait;


class PostController extends \Laravel\Lumen\Routing\Controller
{
    use JSendResponseTrait;

    /**
     * @var PostRepository
     */
    private $postRepository;

    /**
     * @var JSendSerializer
     */
    private $serializer;

    /**
     * @param PostRepository $postRepository
     * @param JSendSerializer $jSendSerializer
     */
    public function __construct(PostRepository $postRepository, JSendSerializer $jSendSerializer)
    {
        $this->postRepository = $postRepository;
        $this->serializer = $jSendSerializer;
    }

    /**
     * @param int $postId
     *
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function getPostAction($postId)
    {
        $post = $this->postRepository->findById($postId);

        /** @var \NilPortugues\Api\JSend\JSendTransformer $transformer */
        $transformer = $this->serializer->getTransformer();
        $transformer->setSelfUrl(route('get_post', ['postId' => $postId]));
        $transformer->setNextUrl(route('get_post', ['postId' => $postId+1]));

        return $this->response($this->serializer->serialize($post));
    }
}

Output:

HTTP/1.1 200 OK
Cache-Control: private, max-age=0, must-revalidate
Content-type: application/json; charset=utf-8

{
    "status": "success",
    "data": {
        "post_id": 9,
        "title": "Hello World",
        "content": "Your first post",
        "author": {
            "user_id": 1,
            "name": "Post Author"
        },
        "comments": [
            {
                "comment_id": 1000,
                "dates": {
                    "created_at": "2015-07-18T12:13:00+00:00",
                    "accepted_at": "2015-07-19T00:00:00+00:00"
                },
                "comment": "Have no fear, sers, your king is safe.",
                "user": {
                    "user_id": 2,
                    "name": "Barristan Selmy"
                }
            }
        ]
    },
    "links": {
        "self": {
            "href": "http://example.com/post/9"
        },
        "next": {
            "href": "http://example.com/post/10"
        }
    }
}

Response objects (JSendResponseTrait)

The following JSendResponseTrait methods are provided to return the right headers and HTTP status codes are available:

    private function errorResponse($message, $code = 500, $data = null);
    private function failResponse($json);
    private function response($json);

To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit.

This library attempts to comply with PSR-1, PSR-2, PSR-4 and PSR-7.

If you notice compliance oversights, please send a patch via Pull Request.

Contributions to the package are always welcome!

• Report any bugs or issues you find on the issue tracker.
• You can grab the source code at the package's Git repository.

Get in touch with me using one of the following means:

• Emailing me at contact@nilportugues.com
• Opening an Issue
• Using Gitter:

• Nil Portugués Calderó
• The Community Contributors

License

The code base is licensed under the MIT license.