nilportugues / json
JSON transformer outputting valid API responses.
Requires
- php: >=5.5.0
- nilportugues/api-transformer: ^1.5
Requires (Dev)
- friendsofphp/php-cs-fixer: ^1.9
- phpunit/phpunit: 4.8.*
README
[] (https://travis-ci.org/nilportugues/php-json) [] (https://coveralls.io/github/nilportugues/json-transformer?branch=master) [] (https://scrutinizer-ci.com/g/nilportugues/json-transformer/?branch=master) [] (https://insight.sensiolabs.com/projects/76f021fa-6559-4faf-a010-5dfb95cd70e2) [] (https://packagist.org/packages/nilportugues/json) [] (https://packagist.org/packages/nilportugues/json) [] (https://packagist.org/packages/nilportugues/json)
Installation
Use Composer to install the package:
$ composer require nilportugues/json
Usage
Given a PHP Object, and a series of mappings, the JSON Transformer will represent the given data as a JSON object.
For instance, given the following piece of code, defining a Blog Post and some comments:
$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 Mapping array for all the involved classes:
use NilPortugues\Api\Mapping\Mapper; $mappings = [ [ 'class' => Post::class, 'alias' => 'Message', 'aliased_properties' => [ 'author' => 'author', 'title' => 'headline', 'content' => 'body', ], 'hide_properties' => [ ], 'id_properties' => [ 'postId', ], 'urls' => [ 'self' => 'http://example.com/posts/{postId}', 'comments' => 'http://example.com/posts/{postId}/comments' ], ], [ 'class' => PostId::class, 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'postId', ], 'urls' => [ 'self' => 'http://example.com/posts/{postId}', ], ], [ 'class' => User::class, 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'userId', ], 'urls' => [ 'self' => 'http://example.com/users/{userId}', 'friends' => 'http://example.com/users/{userId}/friends', 'comments' => 'http://example.com/users/{userId}/comments', ], ], [ 'class' => UserId::class, 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'userId', ], 'urls' => [ 'self' => 'http://example.com/users/{userId}', 'friends' => 'http://example.com/users/{userId}/friends', 'comments' => 'http://example.com/users/{userId}/comments', ], ], [ 'class' => Comment::class, 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'commentId', ], 'urls' => [ 'self' => 'http://example.com/comments/{commentId}', ], ], [ 'class' => CommentId::class, 'alias' => '', 'aliased_properties' => [], 'hide_properties' => [], 'id_properties' => [ 'commentId', ], 'urls' => [ 'self' => 'http://example.com/comments/{commentId}', ], ], ]; $mapper = new Mapper($mappings);
Calling the transformer will output a valid JSON response using the correct formatting:
use NilPortugues\Api\Json\JsonSerializer; use NilPortugues\Api\Json\Http\Message\Response; $serializer = new JsonSerializer($mapper); $output = $serializer->serialize($post); //PSR7 Response with headers and content. $response = new Response($output); header( sprintf( 'HTTP/%s %s %s', $response->getProtocolVersion(), $response->getStatusCode(), $response->getReasonPhrase() ) ); foreach($response->getHeaders() as $header => $values) { header(sprintf("%s:%s\n", $header, implode(', ', $values))); } echo $response->getBody();
Output:
HTTP/1.1 200 OK
Cache-Control: private, 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+02:00", "accepted_at": "2015-07-19T00:00:00+02:00" }, "comment": "Have no fear, sers, your king is safe.", "user": { "user_id": 2, "name": "Barristan Selmy" } } ], "links": { "self": { "href": "http://example.com/posts/9" }, "comments": { "href": "http://example.com/posts/9/comments" } } }
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.