Improve typehints and documentation

phramework · Aug 7, 2016 · a58efbe · a58efbe
1 parent bdcf443
commit a58efbe
Show file tree

Hide file tree

Showing 31 changed files with 566 additions and 141 deletions.
diff --git a/src/CollectionResponse.php b/src/CollectionResponse.php
@@ -0,0 +1,14 @@
+<?php
+declare(strict_types=1);
+
+namespace Phramework\JSONAPI;
+
+/**
+ * @property \Phramework\JSONAPI\Resource[] $data
+ * @property \Phramework\JSONAPI\Resource[] $included
+ * @property \stdClass $meta
+ * @property \stdClass $links
+ */
+abstract class CollectionResponse
+{
+}
diff --git a/src/Controller-legact/POST.php b/src/Controller-legact/POST.php
@@ -376,6 +376,8 @@ protected static function getParsedRelationshipAttributes(
                 )
             );
 
+            //todo allow attribute existing as read, callback to write
+
             $relationship = $modelClass::getRelationship($relationshipKey);
 
             $relationshipModelClass   = $relationship->modelClass;

diff --git a/src/Controller-legact/POST/QueueItem.php b/src/Controller-legact/POST/QueueItem.php
@@ -25,6 +25,7 @@
  * @since 0.0.0
  * @license https://www.apache.org/licenses/LICENSE-2.0 Apache-2.0
  * @author Xenofon Spafaridis <nohponex@gmail.com>
+ * @deprecated
  */
 class QueueItem
 {

diff --git a/src/Controller/Controller.php b/src/Controller/Controller.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *

diff --git a/src/Controller/Delete.php b/src/Controller/Delete.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -42,6 +43,9 @@ public static function handleDelete(
         int $bulkLimit = null,
         array $directives
     ) : ResponseInterface {
+        //Validate id using model's validator
+        $id = $model->getIdAttributeValidator()->parse($id);
+
         //gather data as a queue
 
         //check bulk limit

diff --git a/src/Controller/Get.php b/src/Controller/Get.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *

diff --git a/src/Controller/GetById.php b/src/Controller/GetById.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -48,7 +49,8 @@ public static function handleGetById(
         array $directives = [],
         string $id
     ) : ResponseInterface {
-        //todo filter id if resourceModel filter is set
+        //Validate id using model's validator
+        $id = $model->getIdAttributeValidator()->parse($id);
 
         //Parse request related directives from request
         $directives = Controller::parseDirectives(

diff --git a/src/Controller/Helper/RequestBodyQueue.php b/src/Controller/Helper/RequestBodyQueue.php
@@ -1,5 +1,5 @@
 <?php
-
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -26,7 +26,9 @@
  */
 trait RequestBodyQueue
 {
-
+    /**
+     * @todo
+     */
     public static function handleResource(
         \stdClass $resource,
         ValidationModel $validationModel,

diff --git a/src/Controller/Patch.php b/src/Controller/Patch.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -26,6 +27,7 @@
  * @license https://www.apache.org/licenses/LICENSE-2.0 Apache-2.0
  * @author Xenofon Spafaridis <nohponex@gmail.com>
  * @since 3.0.0
+ * @todo modify to allow batch, remove id ?
  */
 trait Patch
 {
@@ -42,13 +44,16 @@ public static function handlePatch(
         int $bulkLimit = null,
         array $directives
     ) : ResponseInterface {
+        //Validate id using model's validator
+        $id = $model->getIdAttributeValidator()->parse($id);
+
         //gather data as a queue
 
-        //check bulk limit
+        //check bulk limit ??
 
         //on each validate
 
-        //prefer PATCH validation resourceModel
+        //prefer PATCH validation model
         $validationModel = $model->getValidationModel(
             'PATCH'
         );

diff --git a/src/Controller/Post.php b/src/Controller/Post.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -29,9 +30,11 @@
 use Psr\Http\Message\ServerRequestInterface;
 
 /**
+ * Handle HTTP POST request method to create new resources
  * @license https://www.apache.org/licenses/LICENSE-2.0 Apache-2.0
  * @author Xenofon Spafaridis <nohponex@gmail.com>
  * @since 3.0.0
+ * @todo modify to allow batch, remove id ?
  */
 trait Post
 {
@@ -43,18 +46,24 @@ public static function handlePost(
         ResponseInterface $response,
         ResourceModel $model,
         array $validationCallbacks = [],
-        callable $viewCallback = null,
-        int $bulkLimit = null,
-        array $directives
+        callable $viewCallback = null, //function (request, response, $ids) : ResponseInterface
+        int $bulkLimit = null, //todo decide 1 or null for default
+        array $directives = []
     ) : ResponseInterface {
         //Request primary data
         $data = $request->getParsedBody()->data;
 
-        //Treat all request data as an array of resources
+        /**
+         * @var bool
+         */
+        $isBulk = true;
+
+        //Treat all request data (bulk or not) as an array of resources
         if (
             is_object($data)
             || (is_array($data) && Util::isArrayAssoc($data))
         ) {
+            $isBulk = false;
             $data = [$data];
         }
 
@@ -75,43 +84,48 @@ public static function handlePost(
             'POST'
         );
 
-        $index = 0;
+        $bulkIndex = 0;
         //gather data as a queue
         foreach ($data as $resource) {
-            //Request::requireParameters($resource, 'type');
-            //todo remove index if no bulk
-            $source = new Pointer('/data/' . $index );
+            //Prepare exception source
+            $source = new Pointer(
+                '/data' .
+                (
+                    $isBulk
+                    ? '/' . $bulkIndex
+                    : ''
+                )
+            );
 
+            //Require resource type
             Controller::requireProperties($resource, $source, 'type');
 
             //Validate resource type
             $typeValidator
                 ->setSource($source->getPath() . '/type')
                 ->parse($resource->type);
 
+            //Throw exception if resource id is forced
             if (property_exists($resource, 'id')) {
+                //todo include source
                 throw new ForbiddenException(
                     'Unsupported request to create a resource with a client-generated ID'
                 );
             }
 
-            $requestAttributes = (
-                isset($resource->attributes) && $resource->attributes
-                ? $resource->attributes
-                : new \stdClass()
-            );
+            //Fetch request attributes
+            $requestAttributes    = $resource->attributes    ?? new \stdClass();
+            $requestRelationships = $resource->relationships ?? new \stdClass();
 
-            if (property_exists($resource, 'relationships')) {
-                $requestRelationships = $resource->relationships;
-            } else {
-                $requestRelationships = new \stdClass();
-            }
-
-            $queueItem; //todo;
+            //todo use helper class
+            $queueItem = (object) [
+                'attributes'    => $requestAttributes,
+                'relationships' => $requestRelationships
+            ];
 
             $requestQueue->push($queueItem);
 
-            ++$index;
+            ++$bulkIndex;
         }
 
         //on each validate
@@ -122,22 +136,23 @@ public static function handlePost(
         //post
 
         /**
+         * Gather the created ids
          * @var string[]
          */
         $ids = [];
 
+        //process queue
         while (!$requestQueue->isEmpty()) {
             $queueItem = $requestQueue->pop();
 
             $id = $model->post(
                 $queueItem->attributes
             );
 
-            Controller::testUnknownError($id);
-
+            Controller::assertUnknownError($id);
 
             //POST item's relationships
-            $relationships = $queueItem->getRelationships();
+            $relationships = $queueItem->relationships;
 
             foreach ($relationships as $key => $relationship) {
                 //Call post relationship method to post each of relationships pairs
@@ -157,20 +172,25 @@ public static function handlePost(
             $ids[] = $id;
         }
 
-        //return view callback, MUST return a ResponseInterface
+        //return view callback, it MUST return a ResponseInterface
 
         if ($viewCallback !== null) {
             return $viewCallback(
+                $request,
+                $response,
                 $ids
             );
         }
 
         if (count($ids) === 1) {
             //Prepare response with 201 Created status code
-            return Response::created('link' . $ids[0]);
+            return Response::created(
+                $response,
+                'link' . $ids[0] // location
+            );
         }
 
-        //Return 204
-        return Response::noContent();
+        //Return 204 No Content
+        return Response::noContent($response);
     }
 }
diff --git a/src/Controller/Put.php b/src/Controller/Put.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -42,6 +43,9 @@ public static function handlePut(
         int $bulkLimit = null,
         array $directives
     ) : ResponseInterface {
+        //Validate id using model's validator
+        $id = $model->getIdAttributeValidator()->parse($id);
+
         //gather data as a queue
 
         //check bulk limit

diff --git a/src/Controller/Relationship.php b/src/Controller/Relationship.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *

diff --git a/src/Controller/Response.php b/src/Controller/Response.php
@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /**
  * Copyright 2015-2016 Xenofon Spafaridis
  *
@@ -19,6 +20,7 @@
 use Psr\Http\Message\ResponseInterface;
 
 /**
+ * Helper class containing methods for standard HTTP responses
  * @license https://www.apache.org/licenses/LICENSE-2.0 Apache-2.0
  * @author Xenofon Spafaridis <nohponex@gmail.com>
  * @since 3.0.0

diff --git a/src/Directive/Directive.php b/src/Directive/Directive.php
@@ -42,7 +42,7 @@ abstract public static function parseFromRequest(
     /**
      * @param string      $class
      * @param Directive[] $directives
-     * @return Directive|null
+     * @return static|null
      */
     public static function getByClass(string $class, array $directives)
     {

diff --git a/src/GetResponse.php b/src/GetResponse.php