From c80f2caacf0d39cc112a47bbcc9eb3d190008849 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nil=20Portugu=C3=A9s=20Calder=C3=B3?= Date: Wed, 19 Aug 2015 21:35:37 +0200 Subject: [PATCH 1/3] Update README.md --- README.md | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) diff --git a/README.md b/README.md index b5805de..36315ab 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,209 @@ $ composer require nilportugues/jsend ``` +## Usage +Given a PHP Object, and a series of mappings, the **JSend 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: + +```php +$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: + +```php +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: + +```php +use NilPortugues\Api\JSend\JSendTransformer; +use NilPortugues\Api\JSend\Http\Message\Response; +use NilPortugues\Serializer\Serializer; + +$transformer = new JSendTransformer($mapper); + +//Output transformation +$serializer = new Serializer($transformer); +$serializer->setSelfUrl('http://example.com/posts/9'); +$serializer->setNextUrl('http://example.com/posts/10'); +$serializer->addMeta('author',[['name' => 'Nil Portugués Calderó', 'email' => 'contact@nilportugues.com']]); + +$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 +``` + +```json +{ + "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": "http://example.com/post/9" + }, + "next": { + "href": "http://example.com/post/10" + } + } +} +``` + ## Quality To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit. From 2804a9b1be4d99ef45d7f3e3abd0252b76f0b5d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nil=20Portugu=C3=A9s=20Calder=C3=B3?= Date: Wed, 19 Aug 2015 21:37:35 +0200 Subject: [PATCH 2/3] Update README.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 36315ab..393cc5b 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,9 @@ Content-type: application/json; charset=utf-8 }, "next": { "href": "http://example.com/post/10" + }, + "comments": { + "href": "http://example.com/post/9/comments" } } } From b07703d63f5033469cebf9305e778825958f9eae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nil=20Portugu=C3=A9s=20Calder=C3=B3?= Date: Fri, 28 Aug 2015 17:02:41 +0200 Subject: [PATCH 3/3] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 393cc5b..8642d3b 100644 --- a/README.md +++ b/README.md @@ -154,12 +154,12 @@ Calling the transformer will output a **valid JSON response** using the correct ```php use NilPortugues\Api\JSend\JSendTransformer; use NilPortugues\Api\JSend\Http\Message\Response; -use NilPortugues\Serializer\Serializer; +use NilPortugues\Serializer\DeepCopySerializer; $transformer = new JSendTransformer($mapper); //Output transformation -$serializer = new Serializer($transformer); +$serializer = new DeepCopySerializer($transformer); $serializer->setSelfUrl('http://example.com/posts/9'); $serializer->setNextUrl('http://example.com/posts/10'); $serializer->addMeta('author',[['name' => 'Nil Portugués Calderó', 'email' => 'contact@nilportugues.com']]);