Compatible with Laravel 5.0, 5.1 & 5.2
Use Composer to install the package:
$ composer require nilportugues/laravel5-jsend
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.php
and 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": "https://example.com/post/9"
},
"next": {
"href": "https://example.com/post/10"
}
}
}
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);
## 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 [email protected]
- Opening an Issue
- Using Gitter:
## Authors
The code base is licensed under the MIT license.