Merge branch 'master' of github.com:nilportugues/jsend-transformer

nilportugues · Oct 17, 2015 · 6dee2e1 · 6dee2e1
2 parents 0d1b8e0 + b07703d
commit 6dee2e1
Showing 1 changed file with 206 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,212 @@ $ 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\DeepCopySerializer;
+
+$transformer = new JSendTransformer($mapper);
+
+//Output transformation
+$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']]);
+
+$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"
+        },
+        "comments": {
+            "href": "http://example.com/post/9/comments"
+        }
+    }
+}
+```
+
 ## Quality
 
 To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit.