New response standard with pack feature

Author: yidas

README.md

@@ -23,49 +23,52 @@ class ApiController extends yidas\rest\Controller
 {
     public function index()
     {
-        return $this->json(['bar'=>'foo']);
+        return $this->response->json(['bar'=>'foo']);
     }
 }
 ```
 
-Output:
+Output with status `200 OK`:
 
 ```json
 {"bar":"foo"}
 ```
 
-### Body Formatter
+### RESTful Create Callback
 
 ```php
-try {
-    throw new Exception("API forbidden", 403);
-} catch (\Exception $e) {
-    return $this->json(['bar'=>'foo'], true, $e->getCode(), $e->getMessage());
-}
+public function store($resourceID, $requestData=null) {
 
+    $this->db->insert('mytable', $requestData);
+    $id = $this->db->insert_id();
+    
+    return $this->response->json(['id'=>$id], 201);
+}
 ```
 
-Output:
+Output with status `201 Created`:
 
 ```json
-{"code":403,"message":"API forbidden","data":{"bar":"foo"}}
+{"id":1}
 ```
 
-### Update Example
+### Packed Standard Format
 
 ```php
-public function update($resourceID, $requestData=null) {
-
-    $this->db->where('id', $resourceID)
-        ->update('table', $requestData);
-    return $this->json(false, true);
+try {
+    throw new Exception("API forbidden", 403);
+} catch (\Exception $e) {
+    // Pack data into a standard format
+    $data = $this->pack(['bar'=>'foo'], $e->getCode(), $e->getMessage());
+    return $this->response->json($data, $e->getCode());
 }
+
 ```
 
-Output:
+Output with status `403 Forbidden`:
 
 ```json
-{"code":200}
+{"code":403,"message":"API forbidden","data":{"bar":"foo"}}
 ```
 
 ---
@@ -102,7 +105,7 @@ CONFIGURATION
 1. Create a controller to extend `yidas\rest\Controller`, 
 
 ```php
-class ApiController extends yidas\rest\Controller {}
+class ResourceController extends yidas\rest\Controller {}
 ```
 
 2. Add and implement action methods referring by [Build Methods](#build-methods).
@@ -189,7 +192,7 @@ You could override to defind your own routing while creating a resource controll
 class ApiController extends yidas\rest\Controller {
 
     protected $routes = [
-        'index' => '_list',
+        'index' => 'find',
         'store' => 'save',
         'show' => 'display',
         'update' => 'edit',
@@ -198,27 +201,34 @@ class ApiController extends yidas\rest\Controller {
 }
 ```
 
-> The keys are refered to Action of Resource Controller table. 
+> The keys are refered to Action of Resource Controller table, you must define all routes you need. 
 >
-> For example: REST list `index` action will run `_list` method.
+> For example: REST list `index` action will run `find` method.
 
 
 ### Usage
 
-#### json()
+#### `pack()`
 
-Output by JSON format with optinal body format
+Pack array data into body format
 
-|Item|Type|Description|
-|-|-|-|
-|param|array\|mixed |Callback data body|
-|param| bool |Enable body format|
-|param| int |Callback status code|
-|param| string |Callback status text|
-|return |string| Response body data|
+You could override this method for your application standard.
 
 ```php
-return $this->json(["bar"=>"foo"], true);
+$data = $this->pack(['bar'=>'foo'], 403, 'Forbidden');
+return $this->response->json($data, 403);
+```
+
+JSON Result:
+
+```
+{
+    "code": 403,
+    "message": "Forbidden",
+    "data": {
+        "bar": "foo"
+    }
+}
 ```
 
 ---
@@ -230,13 +240,13 @@ The PSR-7 request component `yidas\http\request` is loaded with `yidas\rest\Cont
 
 ### Usage
 
-#### getAuthCredentialsWithBasic()
+#### `getAuthCredentialsWithBasic()`
 
 ```php
 list($username, $password) = $this->request->getAuthCredentialsWithBasic();
 ```
 
-#### getAuthCredentialsWithBearer()
+#### `getAuthCredentialsWithBearer()`
 
 ```php
 $b64token = $this->request->getAuthCredentialsWithBearer();
@@ -251,19 +261,27 @@ The PSR-7 response component `yidas\http\response` is loaded with `yidas\rest\Co
 
 ### Usage
 
-#### setFormat()
+#### `json()`
+
+JSON output shortcut
+
+```php
+$this->response->json(['bar'=>'foo'], 201);
+```
+
+#### `setFormat()`
 
 ```php
 $this->response->setFormat(\yidas\http\Response::FORMAT_JSON);
 ```
 
-#### setData()
+#### `setData()`
 
 ```php
 $this->response->setData(['foo'=>'bar']);
 ```
 
-#### send()
+#### `send()`
 
 ```php
 $this->response->send();

src/http/Response.php

@@ -225,8 +225,12 @@ public function json($data, $statusCode=null)
             $this->setStatusCode($statusCode);
         }
 
-        return $this->setFormat(Response::FORMAT_JSON)
-            ->setData($data)
-            ->send();
+        $this->setFormat(Response::FORMAT_JSON);
+
+        if (!is_null($data)) {
+            $this->setData($data);
+        }
+        
+        return $this->send();
     }
 }

src/rest/Controller.php

@@ -9,7 +9,7 @@
  * RESTful API Controller
  * 
  * @author  Nick Tsai <myintaer@gmail.com>
- * @version 1.2.0
+ * @version 1.3.0
  * @link    https://github.com/yidas/codeigniter-rest/
  * @see     https://github.com/yidas/codeigniter-rest/blob/master/examples/RestController.php
  * 
@@ -26,15 +26,6 @@
  */
 class Controller extends \CI_Controller
 {
-    /**
-     * @var array Standard format
-     */
-    protected $responseFormat = [
-        'status_code' => 'code',
-        'message' => 'message',
-        'body' => 'data',
-    ];
-
     /**
      * RESTful API resource routes
      * 
@@ -144,6 +135,7 @@ public function ajax($resourceID=NULL)
     /**
      * Output by JSON format with optinal body format
      * 
+     * @deprecated 1.3.0
      * @param array|mixed Callback data body, false will remove body key
      * @param bool Enable body format
      * @param int HTTP Status Code
@@ -172,6 +164,7 @@ protected function json($data=[], $bodyFormat=null, $statusCode=null, $message=n
     /**
      * Format Response Data
      * 
+     * @deprecated 1.3.0
      * @param int Callback status code
      * @param string Callback status text
      * @param array|mixed|bool Callback data body, false will remove body key 
@@ -195,6 +188,41 @@ protected function _format($statusCode=null, $message=null, $body=false)
         return $format;
     }
 
+    /**
+     * Pack array data into body format
+     * 
+     * You could override this method for your application standard
+     * 
+     * @param array|string $data Original data
+     * @param int HTTP Status Code
+     * @param string Callback message
+     * @return array Packed data
+     * @example
+     *  $packedData = pack(['bar'=>'foo], 401, 'Login Required');
+     */
+    protected function pack($data, $statusCode=200, $message=null)
+    {
+        $packBody = [];
+
+        // Status Code
+        if ($statusCode) {
+            
+            $packBody['code'] = $statusCode;
+        }
+        // Message
+        if ($message) {
+            
+            $packBody['message'] = $message;
+        }
+        // Data
+        if (is_array($data) || is_string($data)) {
+            
+            $packBody['data'] = $data;
+        }
+        
+        return $packBody;
+    }
+
     /**
      * Default Action
      */