nilportugues / laravel5-haljson
Laravel 5 HAL+JSON API Transformer Package
Requires
Requires (Dev)
- fabpot/php-cs-fixer: ^1.10
- laravel/laravel: ^5
- phpunit/phpunit: ^4
README
1. Installation
Use Composer to install the package:
$ composer require nilportugues/laravel5-haljson
2. Configuration
Open up config/app.php
and add the following line under providers
array:
'providers' => [ //... \NilPortugues\Laravel5\HalJson\Laravel5HalJsonServiceProvider::class, ],
Also, enable Facades by uncommenting:
$app->withFacades();
3. Mapping
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'), ] ), ] );
We will have to map all the involved classes. This can be done as one single array, or a series of Mapping classes.
Also we will require to have routes. The routes must be named routes.
For instance our app/Http/routes.php
file contains the following routes:
Route::get( '/docs/rels/{rel}', ['as' => 'get_example_curie_rel', 'uses' => 'ExampleCurieController@getRelAction'] ); Route::get( '/post/{postId}', ['as' => 'get_post', 'uses' => 'PostController@getPostAction'] ); Route::get( '/post/{postId}/comments', ['as' => 'get_post_comments', 'uses' => 'CommentsController@getPostCommentsAction'] ); //...
3.1 Mapping with arrays
Create a haljson.php
file in config/
directory. This file should return an array returning all the class mappings.
And a series of mappings, placed in bootstrap/haljson.php
, that require to use named routes so we can use the route()
helper function:
<?php //bootstrap/haljson.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 ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], [ 'class' => 'Acme\Domain\Dummy\ValueObject\PostId', 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'postId', ], 'urls' => [ 'self' => ['name' => 'get_post'],//named route ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], [ '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 ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], [ '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 ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], [ 'class' => 'Acme\Domain\Dummy\Comment', 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'commentId', ], 'urls' => [ 'self' => ['name' => 'get_comment'],//named route ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], [ 'class' => 'Acme\Domain\Dummy\ValueObject\CommentId', 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'commentId', ], 'urls' => [ 'self' => ['name' => 'get_comment'],//named route ], 'curies' => [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ] ], ];
3.2 Mapping with Mapping class
In order to map with Mapping class, you need to create a new class for each involved class.
This mapping fashion scales way better than using an array. Place each mapping in a separate file.
All Mapping classes will extend the \NilPortugues\Api\Mappings\HalMapping
interface.
<?php class PostMapping implements \NilPortugues\Api\Mappings\HalMapping { public function getClass() { return 'Acme\Domain\Dummy\Post'; } public function getAlias() { return 'Message'; } public function getAliasedProperties() { return [ 'author' => 'author', 'title' => 'headline', 'content' => 'body', ]; } public function getHideProperties() { return []; } public function getIdProperties() { return ['postId']; } public function getUrls() { return [ 'self' => ['name' => 'get_post'], //named route 'comments' => ['name' => 'get_post_comments'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } } class PostIdMapping implements \NilPortugues\Api\Mappings\HalMapping{ public function getClass() { return 'Acme\Domain\Dummy\ValueObject\PostId'; } public function getAlias() { return ''; } public function getAliasedProperties() { return []; } public function getHideProperties() { return []; } public function getIdProperties() { return ['postId']; } public function getUrls() { return [ 'self' => ['name' => 'get_post'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } } class UserMapping implements \NilPortugues\Api\Mappings\HalMapping{ public function getClass() { return 'Acme\Domain\Dummy\User'; } public function getAlias() { return ''; } public function getAliasedProperties() { return []; } public function getHideProperties() { return []; } public function getIdProperties() { return ['userId']; } public function getUrls() { return [ 'self' => ['name' => 'get_user'],//named route 'friends' => ['name' => 'get_user_friends'],//named route 'comments' => ['name' => 'get_user_comments'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } } class UserIdMapping implements \NilPortugues\Api\Mappings\HalMapping{ public function getClass() { return 'Acme\Domain\Dummy\ValueObject\UserId'; } public function getAlias() { return ''; } public function getAliasedProperties() { return []; } public function getHideProperties() { return []; } public function getIdProperties() { return ['userId']; } public function getUrls() { return [ 'self' => ['name' => 'get_user'],//named route 'friends' => ['name' => 'get_user_friends'],//named route 'comments' => ['name' => 'get_user_comments'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } } class CommentMapping implements \NilPortugues\Api\Mappings\HalMapping{ public function getClass() { return 'Acme\Domain\Dummy\Comment'; } public function getAlias() { return ''; } public function getAliasedProperties() { return []; } public function getHideProperties() { return []; } public function getIdProperties() { return ['commentId']; } public function getUrls() { return [ 'self' => ['name' => 'get_comment'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } } class CommentIdMapping implements \NilPortugues\Api\Mappings\HalMapping{ public function getClass() { return 'Acme\Domain\Dummy\ValueObject\CommentId'; } public function getAlias() { return ''; } public function getAliasedProperties() { return []; } public function getHideProperties() { return []; } public function getIdProperties() { return ['commentId']; } public function getUrls() { return [ 'self' => ['name' => 'get_comment'],//named route ]; } public function getCuries() { return [ 'name' => 'example', 'href' => "http://example.com/docs/rels/{rel}", ]; } }
All the mappings will be contained in the array in the bootstrap/haljson.php
, but this time the fully qualified class name is required instead.
<?php //bootstrap/haljson.php return [ "\Acme\Mappings\PostMapping", "\Acme\Mappings\PostIdMapping", "\Acme\Mappings\UserMapping", "\Acme\Mappings\UserIdMapping", "\Acme\Mappings\CommentMapping", "\Acme\Mappings\CommentIdMapping", ];
3. HAL Serialization
All of this set up allows you to easily use the Serializer
service as follows:
<?php namespace App\Http\Controllers; use Acme\Domain\Dummy\PostRepository; use NilPortugues\Laravel5\HalJson\HalJsonResponseTrait; class PostController extends \App\Http\Controllers\Controller { use HalJsonResponseTrait; /** * @var PostRepository */ protected $postRepository; /** * @var HalJson */ protected $serializer; /** * @param PostRepository $postRepository * @param HalJson $HalJson */ public function __construct(PostRepository $postRepository, HalJson $HalJson) { $this->postRepository = $postRepository; $this->serializer = $HalJson; } /** * @param int $postId * * @return \Symfony\Component\HttpFoundation\Response */ public function getPostAction($postId) { $post = $this->postRepository->findById($postId); return $this->response($this->serializer->serialize($post)); } }
Output:
HTTP/1.1 200 OK
Cache-Control: protected, max-age=0, must-revalidate
Content-type: application/hal+json
{ "post_id": 9, "headline": "Hello World", "body": "Your first post", "_embedded": { "author": { "user_id": 1, "name": "Post Author", "_links": { "self": { "href": "http://example.com/users/1" }, "example:friends": { "href": "http://example.com/users/1/friends" }, "example:comments": { "href": "http://example.com/users/1/comments" } } }, "comments": [ { "comment_id": 1000, "dates": { "created_at": "2015-08-13T22:47:45+02:00", "accepted_at": "2015-08-13T23:22:45+02:00" }, "comment": "Have no fear, sers, your king is safe.", "_embedded": { "user": { "user_id": 2, "name": "Barristan Selmy", "_links": { "self": { "href": "http://example.com/users/2" }, "example:friends": { "href": "http://example.com/users/2/friends" }, "example:comments": { "href": "http://example.com/users/2/comments" } } } }, "_links": { "example:user": { "href": "http://example.com/users/2" }, "self": { "href": "http://example.com/comments/1000" } } } ] }, "_links": { "curies": [ { "name": "example", "href": "http://example.com/docs/rels/{rel}", "templated": true } ], "self": { "href": "http://example.com/posts/9" }, "example:author": { "href": "http://example.com/users/1" }, "example:comments": { "href": "http://example.com/posts/9/comments" } } }
5. HAL Paginated Resource
A pagination object to easy the usage of this package is provided.
For both XML and JSON output, use the HalPagination
object to build your paginated representation of the current resource.
Methods provided by HalPagination
are as follows:
setSelf($self)
setFirst($first)
setPrev($prev)
setNext($next)
setLast($last)
setCount($count)
setTotal($total)
setEmbedded(array $embedded)
In order to use it, create a new HalPagination instance, use the setters and pass the instance to the serialize($value)
method of the serializer.
Everything else will be handled by serializer itself. Easy as that!
use NilPortugues\Api\Hal\HalPagination; use NilPortugues\Api\Hal\HalSerializer; use NilPortugues\Api\Hal\JsonTransformer; // ... //$objects is an array of objects, such as Post::class. // ... $page = new HalPagination(); //set the amounts $page->setTotal(20); $page->setCount(10); //set the objects $page->setEmbedded($objects); //set up the pagination links $page->setSelf('/post?page=1'); $page->setPrev('/post?page=1'); $page->setFirst('/post?page=1'); $page->setLast('/post?page=1'); $output = $serializer->serialize($page);
6. Response objects
The following HalJsonResponseTrait
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
Authors
License
The code base is licensed under the MIT license.