v0.5.0

neomerx · Jun 10, 2015 · 6e00891 · 6e00891
2 parents 9d18161 + 386b217
commit 6e00891
Show file tree

Hide file tree

Showing 61 changed files with 1,562 additions and 1,742 deletions.
diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@ Assuming you've got an ```$author``` of type ```\Author``` you can encode it to
 ```php
 $encoder = Encoder::instance([
     '\Author' => '\AuthorSchema',
-], new JsonEncodeOptions(JSON_PRETTY_PRINT));
+], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com/api/v1'));
 
 echo $encoder->encode($author) . PHP_EOL;
 ```
@@ -52,7 +52,7 @@ will output
             "last_name": "Dow"
         },
         "links": {
-            "self": "http:\/\/example.com\/people\/123"
+            "self": "http://example.com/api/v1/people/123"
         }
     }
 }
@@ -64,7 +64,7 @@ The ```AuthorSchema``` provides information about resource's attributes and migh
 class AuthorSchema extends SchemaProvider
 {
     protected $resourceType = 'people';
-    protected $baseSelfUrl  = 'http://example.com/people/';
+    protected $selfSubUrl   = '/people/';
 
     public function getId($author)
     {
@@ -83,6 +83,10 @@ class AuthorSchema extends SchemaProvider
 }
 ```
 
+The first ```EncoderOptions``` parameter ```JSON_PRETTY_PRINT``` is a PHP predefined [JSON constant](http://php.net/manual/en/json.constants.php).
+
+The second ```EncoderOptions``` parameter ```http://example.com/api/v1``` is a URL prefix that will be applied to all encoded links unless they have ```$treatAsHref``` flag set to ```true```.
+
 **For more advanced usage please check out the [Wiki](https://github.com/neomerx/json-api/wiki)**.
 
 ## Questions?

diff --git a/sample/composer.json b/sample/composer.json
@@ -16,6 +16,6 @@
     },
     "minimum-stability": "dev",
     "require": {
-        "neomerx/json-api": "0.4.2"
+        "neomerx/json-api": "~0.5.0"
     }
 }
diff --git a/sample/sample.php b/sample/sample.php
@@ -18,7 +18,7 @@
 
 use \Neomerx\JsonApi\Schema\Link;
 use \Neomerx\JsonApi\Encoder\Encoder;
-use \Neomerx\JsonApi\Encoder\JsonEncodeOptions;
+use \Neomerx\JsonApi\Encoder\EncoderOptions;
 use \Neomerx\JsonApi\Parameters\EncodingParameters;
 
 require './vendor/autoload.php';
@@ -39,7 +39,7 @@ private function showBasicExample()
 
         $encoder = Encoder::instance([
             Author::class  => AuthorSchema::class,
-        ], new JsonEncodeOptions(JSON_PRETTY_PRINT));
+        ], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com/api/v1'));
 
         echo $encoder->encode($author) . PHP_EOL;
     }
@@ -64,7 +64,7 @@ private function showIncludedObjectsExample()
             Comment::class => CommentSchema::class,
             Post::class    => PostSchema::class,
             Site::class    => SiteSchema::class
-        ], new JsonEncodeOptions(JSON_PRETTY_PRINT));
+        ], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com'));
 
         echo $encoder->encode($site) . PHP_EOL;
     }
@@ -97,7 +97,7 @@ private function showSparseAndFieldSetsExample()
             Comment::class => CommentSchema::class,
             Post::class    => PostSchema::class,
             Site::class    => SiteSchema::class
-        ], new JsonEncodeOptions(JSON_PRETTY_PRINT));
+        ], new EncoderOptions(JSON_PRETTY_PRINT));
 
         echo $encoder->encode($site, null, null, $options) . PHP_EOL;
     }
@@ -119,18 +119,18 @@ private function showTopLevelMetaAndLinksExample()
             ]
         ];
         $links  = [
-            Link::FIRST => new Link('http://example.com/people?first'),
-            Link::LAST  => new Link('http://example.com/people?last'),
-            Link::PREV  => new Link('http://example.com/people?prev'),
-            Link::NEXT  => new Link('http://example.com/people?next'),
+            Link::FIRST => new Link('http://example.com/people?first', null, true),
+            Link::LAST  => new Link('http://example.com/people?last', null, true),
+            Link::PREV  => new Link('http://example.com/people?prev', null, true),
+            Link::NEXT  => new Link('http://example.com/people?next', null, true),
         ];
 
         $encoder  = Encoder::instance([
             Author::class  => AuthorSchema::class,
             Comment::class => CommentSchema::class,
             Post::class    => PostSchema::class,
             Site::class    => SiteSchema::class
-        ], new JsonEncodeOptions(JSON_PRETTY_PRINT));
+        ], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com'));
 
         echo $encoder->encode($author, $links, $meta) . PHP_EOL;
     }
@@ -166,7 +166,7 @@ private function runPerformanceTest($iterations)
 
             $encoder->encode(
                 $site,
-                [Link::SELF => new Link('http://example.com/sites/1?' . $rand)],
+                [Link::SELF => new Link('http://example.com/sites/1?' . $rand, null, true)],
                 ['some' => ['meta' => 'information' . $rand]],
                 $options
             );

diff --git a/sample/schemas/AuthorSchema.php b/sample/schemas/AuthorSchema.php
@@ -24,7 +24,7 @@
 class AuthorSchema extends SchemaProvider
 {
     protected $resourceType = 'people';
-    protected $baseSelfUrl  = 'http://example.com/people/';
+    protected $selfSubUrl  = '/people/';
 
     public function getId($author)
     {

diff --git a/sample/schemas/CommentSchema.php b/sample/schemas/CommentSchema.php
@@ -24,7 +24,7 @@
 class CommentSchema extends SchemaProvider
 {
     protected $resourceType = 'comments';
-    protected $baseSelfUrl  = 'http://example.com/comments/';
+    protected $selfSubUrl  = '/comments/';
 
     protected $isShowSelfInIncluded = true;
 

diff --git a/sample/schemas/PostSchema.php b/sample/schemas/PostSchema.php
@@ -24,7 +24,7 @@
 class PostSchema extends SchemaProvider
 {
     protected $resourceType = 'posts';
-    protected $baseSelfUrl  = 'http://example.com/posts';
+    protected $selfSubUrl  = '/posts/';
 
     public function getId($post)
     {

diff --git a/sample/schemas/SiteSchema.php b/sample/schemas/SiteSchema.php
@@ -24,7 +24,7 @@
 class SiteSchema extends SchemaProvider
 {
     protected $resourceType = 'sites';
-    protected $baseSelfUrl  = 'http://example.com/sites';
+    protected $selfSubUrl  = '/sites/';
 
     public function getId($site)
     {

diff --git a/src/Codec/CodecMatcher.php b/src/Codec/CodecMatcher.php
@@ -52,12 +52,12 @@ class CodecMatcher implements CodecMatcherInterface
     private $inputMediaTypes;
 
     /**
-     * @var EncoderInterface|null
+     * @var EncoderInterface|Closure|null
      */
     private $foundEncoder;
 
     /**
-     * @var DecoderInterface|null
+     * @var DecoderInterface|Closure|null
      */
     private $foundDecoder;
 
@@ -102,17 +102,43 @@ public function registerDecoder(MediaTypeInterface $mediaType, Closure $decoderC
      */
     public function getEncoder()
     {
+        if ($this->foundEncoder instanceof Closure) {
+            $closure = $this->foundEncoder;
+            $this->foundEncoder = $closure();
+        }
+
         return $this->foundEncoder;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function setEncoder($encoder)
+    {
+        $this->foundEncoder = $encoder;
+    }
+
     /**
      * @inheritdoc
      */
     public function getDecoder()
     {
+        if ($this->foundDecoder instanceof Closure) {
+            $closure = $this->foundDecoder;
+            $this->foundDecoder = $closure();
+        }
+
         return $this->foundDecoder;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function setDecoder($decoder)
+    {
+        $this->foundDecoder = $decoder;
+    }
+
     /**
      * @inheritdoc
      */
@@ -126,7 +152,7 @@ public function matchEncoder(AcceptHeaderInterface $acceptHeader)
                     if ($registeredType->matchesTo($headerMediaType) === true) {
                         $this->encoderHeaderMatchedType     = $headerMediaType;
                         $this->encoderRegisteredMatchedType = $registeredType;
-                        $this->foundEncoder                 = $closure();
+                        $this->foundEncoder                 = $closure;
 
                         return;
                     }
@@ -154,7 +180,7 @@ public function findDecoder(HeaderInterface $contentTypeHeader)
                 if ($registeredType->equalsTo($headerMediaType) === true) {
                     $this->decoderHeaderMatchedType     = $headerMediaType;
                     $this->decoderRegisteredMatchedType = $registeredType;
-                    $this->foundDecoder                 = $closure();
+                    $this->foundDecoder                 = $closure;
 
                     return;
                 }

diff --git a/src/Contracts/Codec/CodecMatcherInterface.php b/src/Contracts/Codec/CodecMatcherInterface.php
@@ -56,13 +56,31 @@ public function registerDecoder(MediaTypeInterface $mediaType, Closure $decoderC
      */
     public function getEncoder();
 
+    /**
+     * Set encoder.
+     *
+     * @param EncoderInterface|Closure $encoder
+     *
+     * @return void
+     */
+    public function setEncoder($encoder);
+
     /**
      * Get decoder.
      *
      * @return DecoderInterface|null
      */
     public function getDecoder();
 
+    /**
+     * Set decoder.
+     *
+     * @param DecoderInterface|Closure $decoder
+     *
+     * @return DecoderInterface
+     */
+    public function setDecoder($decoder);
+
     /**
      * Find best encoder match for 'Accept' header.
      *

diff --git a/src/Contracts/Document/DocumentFactoryInterface.php b/src/Contracts/Document/DocumentFactoryInterface.php
@@ -16,6 +16,8 @@
  * limitations under the License.
  */
 
+use \Neomerx\JsonApi\Contracts\Schema\LinkInterface;
+
 /**
  * @package Neomerx\JsonApi
  */
@@ -31,20 +33,20 @@ public function createDocument();
     /**
      * Create error instance.
      *
-     * @param int|string|null $idx
-     * @param string|null     $href
-     * @param string|null     $status
-     * @param string|null     $code
-     * @param string|null     $title
-     * @param string|null     $detail
-     * @param mixed|null      $source
-     * @param array|null      $meta
+     * @param int|string|null    $idx
+     * @param LinkInterface|null $aboutLink
+     * @param string|null        $status
+     * @param string|null        $code
+     * @param string|null        $title
+     * @param string|null        $detail
+     * @param mixed|null         $source
+     * @param array|null         $meta
      *
      * @return ErrorInterface
      */
     public function createError(
         $idx = null,
-        $href = null,
+        LinkInterface $aboutLink = null,
         $status = null,
         $code = null,
         $title = null,

diff --git a/src/Contracts/Document/DocumentInterface.php b/src/Contracts/Document/DocumentInterface.php
@@ -57,13 +57,17 @@ interface DocumentInterface
     const KEYWORD_DATA          = 'data';
     /** Reserved keyword */
     const KEYWORD_INCLUDED      = 'included';
+    /** Reserved keyword */
+    const KEYWORD_JSON_API      = 'jsonapi';
+    /** Reserved keyword */
+    const KEYWORD_VERSION       = 'version';
 
     /** Reserved keyword */
     const KEYWORD_ERRORS        = 'errors';
     /** Reserved keyword */
     const KEYWORD_ERRORS_ID     = 'id';
     /** Reserved keyword */
-    const KEYWORD_ERRORS_HREF   = 'href';
+    const KEYWORD_ERRORS_LINKS  = self::KEYWORD_LINKS;
     /** Reserved keyword */
     const KEYWORD_ERRORS_STATUS = 'status';
     /** Reserved keyword */
@@ -76,11 +80,13 @@ interface DocumentInterface
     const KEYWORD_ERRORS_META   = 'meta';
     /** Reserved keyword */
     const KEYWORD_ERRORS_SOURCE = 'source';
+    /** Reserved keyword */
+    const KEYWORD_ERRORS_ABOUT  = 'about';
 
     /**
      * Set URLs to top-level 'links' section.
      *
-     * @param LinkInterface[]|null $links
+     * @param array<string,LinkInterface>|null $links
      *
      * @return void
      */
@@ -133,16 +139,6 @@ public function addRelationshipToData(
         ResourceObjectInterface $resource
     );
 
-    /**
-     * Add a reference to resource in 'data' section.
-     *
-     * @param ResourceObjectInterface     $parent
-     * @param RelationshipObjectInterface $current
-     *
-     * @return void
-     */
-    public function addReferenceToData(ResourceObjectInterface $parent, RelationshipObjectInterface $current);
-
     /**
      * Add an empty relationship to resource in 'data' section.
      *
@@ -187,16 +183,6 @@ public function addRelationshipToIncluded(
         ResourceObjectInterface $resource
     );
 
-    /**
-     * Add a reference to resource in 'included' section.
-     *
-     * @param ResourceObjectInterface     $parent
-     * @param RelationshipObjectInterface $current
-     *
-     * @return void
-     */
-    public function addReferenceToIncluded(ResourceObjectInterface $parent, RelationshipObjectInterface $current);
-
     /**
      * Add an empty relationship to resource in 'included' section.
      *
@@ -243,6 +229,29 @@ public function setResourceCompleted(ResourceObjectInterface $resource);
      */
     public function addError(ErrorInterface $error);
 
+    /**
+     * Add JSON API version information.
+     *
+     * @link http://jsonapi.org/format/#document-jsonapi-object
+     *
+     * @param string     $version
+     * @param mixed|null $meta
+     *
+     * @return void
+     */
+    public function addJsonApiVersion($version, $meta = null);
+
+    /**
+     * Set a prefix that will be applied to all URLs in the document except marked as href.
+     *
+     * @see LinkInterface
+     *
+     * @param string $prefix
+     *
+     * @return void
+     */
+    public function setUrlPrefix($prefix);
+
     /**
      * Remove 'data' top-level section.
      *