Add schema version support

src/GW2Api.php

@@ -53,8 +53,12 @@
 use GW2Treasures\GW2Api\V2\IEndpoint;
 use GW2Treasures\GW2Api\V2\Localization\LocalizationHandler;
 use GW2Treasures\GW2Api\V2\Pagination\PaginationHandler;
+use GW2Treasures\GW2Api\V2\Schema\SchemaHandler;
 
 class GW2Api {
+    /** @const string */
+    const DEFAULT_SCHEMA = '2019-03-20T00:00:00Z';
+
     /** @var string $apiUrl */
     protected $apiUrl = 'https://api.guildwars2.com/';
 
@@ -67,6 +71,9 @@ class GW2Api {
     /** @var array $handlers */
     protected $handlers = [];
 
+    /** @var string $schema */
+    protected $schema = self::DEFAULT_SCHEMA;
+
     function __construct( array $options = [] ) {
         $this->options = $this->getOptions( $options );
 
@@ -149,6 +156,7 @@ protected function registerDefaultHandlers() {
         $this->registerHandler(LocalizationHandler::class);
         $this->registerHandler(PaginationHandler::class);
         $this->registerHandler(RestrictedGuildHandler::class);
+        $this->registerHandler(SchemaHandler::class);
     }
 
     public function getClient() {
@@ -330,4 +338,25 @@ public function attachRegisteredHandlers( IEndpoint $endpoint ) {
             }
         }
     }
+
+    /**
+     * Set the schema version to use for this api instance.
+     *
+     * @param string $schema
+     * @return $this
+     */
+    public function schema( $schema ) {
+        $this->schema = $schema;
+
+        return $this;
+    }
+
+    /**
+     * Get the schema version used by this api instance.
+     *
+     * @return String
+     */
+    public function getSchema() {
+        return $this->schema;
+    }
 }

src/V2/Endpoint.php

@@ -20,6 +20,9 @@ abstract class Endpoint implements IEndpoint {
     /** @var ApiHandler[] */
     protected $handlers = [];
 
+    /** @var string schema */
+    protected $schema = null;
+
     /**
      * @param GW2Api $api
      */
@@ -43,6 +46,28 @@ protected function getApi() {
         return $this->api;
     }
 
+    /**
+     * Set the schema version to use when requesting this endpoint.
+     *
+     * @param string $schema
+     * @return $this
+     */
+    public function schema( $schema ) {
+        $this->schema = $schema;
+
+        return $this;
+    }
+
+    /**
+     * Get the schema used to request this endpoint.
+     * Falls back to the global schema set in the GW2API instance.
+     *
+     * @return String
+     */
+    public function getSchema() {
+        return $this->schema !== null ? $this->schema : $this->getApi()->getSchema();
+    }
+
     /**
      * Creates a new Request to this Endpoint.
      *

src/V2/IEndpoint.php

@@ -16,4 +16,20 @@ public function attach( ApiHandler $handler );
      * @return string
      */
     public function url();
+
+    /**
+     * Set the schema version to use when requesting this endpoint.
+     *
+     * @param string $schema
+     * @return $this
+     */
+    public function schema( $schema );
+
+    /**
+     * Get the schema used to request this endpoint.
+     * Falls back to the global schema set in the GW2API instance.
+     *
+     * @return String
+     */
+    public function getSchema();
 }

src/V2/Schema/SchemaHandler.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace GW2Treasures\GW2Api\V2\Schema;
+
+use GW2Treasures\GW2Api\V2\ApiHandler;
+use GW2Treasures\GW2Api\V2\IEndpoint;
+use Psr\Http\Message\MessageInterface;
+use Psr\Http\Message\RequestInterface;
+
+class SchemaHandler extends ApiHandler {
+    function __construct( IEndpoint $endpoint ) {
+        parent::__construct( $endpoint );
+    }
+
+    /**
+     * Add the schema version header.
+     *
+     * @param RequestInterface $request
+     *
+     * @return MessageInterface|RequestInterface
+     */
+    public function onRequest( RequestInterface $request ) {
+        $schema = $this->getEndpoint()->getSchema();
+
+        return $request->withHeader( 'X-Schema-Version', $schema );
+    }
+}

tests/SchemaTest.php

@@ -0,0 +1,58 @@
+<?php
+
+use GW2Treasures\GW2Api\GW2Api;
+use Stubs\EndpointStub;
+
+const EXPECTED_DEFAULT_SCHEMA = GW2Api::DEFAULT_SCHEMA;
+const EXPECTED_CUSTOM_SCHEMA = '2077-01-01T00:00:00Z';
+
+class SchemaTest extends TestCase {
+    protected function getEndpoint() {
+        return new EndpointStub( $this->api() );
+    }
+
+    public function testDefaultSchema() {
+        $this->mockResponse('[]');
+
+        $endpoint = $this->getEndpoint();
+
+        $this->assertEquals(EXPECTED_DEFAULT_SCHEMA, $endpoint->getSchema());
+
+        $endpoint->test();
+
+        $request = $this->getLastRequest();
+        $this->assertHasHeader($request, 'X-Schema-Version', EXPECTED_DEFAULT_SCHEMA);
+    }
+
+    public function testCustomSchema() {
+        $this->mockResponse('[]');
+
+        $endpoint = $this->getEndpoint()->schema(EXPECTED_CUSTOM_SCHEMA);
+
+        $this->assertEquals(EXPECTED_CUSTOM_SCHEMA, $endpoint->getSchema());
+
+        $endpoint->test();
+
+        $request = $this->getLastRequest();
+        $this->assertHasHeader($request, 'X-Schema-Version', EXPECTED_CUSTOM_SCHEMA);
+    }
+
+    public function testGlobalSchema() {
+        $this->mockResponse('[]');
+
+        $endpoint = $this->getEndpoint();
+        $this->assertEquals(EXPECTED_DEFAULT_SCHEMA, $endpoint->getSchema());
+
+        $this->api()->schema(EXPECTED_CUSTOM_SCHEMA);
+
+        $this->assertEquals(EXPECTED_CUSTOM_SCHEMA, $endpoint->getSchema());
+
+        $endpoint->test();
+
+        $request = $this->getLastRequest();
+        $this->assertHasHeader($request, 'X-Schema-Version', EXPECTED_CUSTOM_SCHEMA);
+
+        // clean up schema for other tests
+        $this->resetApi();
+    }
+}

tests/TestCase.php

@@ -39,6 +39,10 @@ protected function api() {
         return $this->api;
     }
 
+    protected function resetApi() {
+        unset($this->api);
+    }
+
     /**
      * @param Response|RequestException|string $response
      * @param string $language