nilportugues / laravel5-json
Laravel 5 Json API Transformer Package
Requires
Requires (Dev)
- fabpot/php-cs-fixer: ^1.10
- laravel/laravel: 5.*
- phpunit/phpunit: 4.*
README
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.php
and 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);
## Quality
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.
## Contribute
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.
## Support
Get in touch with me using one of the following means:
- Emailing me at contact@nilportugues.com
- Opening an Issue
- Using Gitter:
## Authors
License
The code base is licensed under the MIT license.