Laravel 5 JSON Transformer Package

Compatible with Laravel 5.0, 5.1 & 5.2

Installation

Use Composer to install the package:

$ composer require nilportugues/laravel5-json

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\Json\Laravel5JsonServiceProvider::class,
],

Lumen

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

$app->register(\NilPortugues\Laravel5\Json\Laravel5JsonServiceProvider::class);
$app->configure('json');

Also, enable Facades by uncommenting:

$app->withFacades();

Step 2: Add the mapping

Create a json.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/json.php, that require to use named routes so we can use the route() helper function:

<?php
//config/json.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 JsonSerializer service as follows:

<?php

namespace App\Http\Controllers;

use Acme\Domain\Dummy\PostRepository;
use NilPortugues\Laravel5\Json\JsonSerializer;
use NilPortugues\Laravel5\Json\JsonResponseTrait;

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

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

    /**
     * @var JsonSerializer
     */
    protected $serializer;

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

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

        /** @var \NilPortugues\Api\Json\JsonTransformer $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: protected, max-age=0, must-revalidate
Content-type: application/json; charset=utf-8

{
    "post_id": 9,
    "headline": "Hello World",
    "body": "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://localhost:8000/post/9"
        },
        "next": {
            "href": "http://localhost:8000/post/10"
        },
        "comments": {
            "href": "http://localhost:8000/post/9/comments"
        }
    }
}

Response objects (JsonResponseTrait)

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

    protected function errorResponse($json);
    protected function resourceCreatedResponse($json);
    protected function resourceDeletedResponse($json);
    protected function resourceNotFoundResponse($json);
    protected function resourcePatchErrorResponse($json);
    protected function resourcePostErrorResponse($json);
    protected function resourceProcessingResponse($json);
    protected function resourceUpdatedResponse($json);
    protected function response($json);
    protected function unsupportedActionResponse($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.