Merge pull request #9 from EtienneLamoureux/1.2.0

1.2.0

README.md

@@ -20,7 +20,7 @@ Add Durmand Scriptorium to your project's composer.json file:
 ```javascript
 {
     "require": {
-        "crystalgorithm/durmand-scriptorium": "~1.1"
+        "crystalgorithm/durmand-scriptorium": "~1.2"
     }
 }
 ```
@@ -54,6 +54,8 @@ Documentation
     - [GetPageRange](https://github.com/EtienneLamoureux/durmand-scriptorium/blob/master/docs/COLLECTION_CONSUMER.md#getpagerange)
 - [Converter consumer](https://github.com/EtienneLamoureux/durmand-scriptorium/blob/master/docs/CONVERTER_CONSUMER.md#converter-consumer)
     - [Convert](https://github.com/EtienneLamoureux/durmand-scriptorium/blob/master/docs/CONVERTER_CONSUMER.md#convert)
+- [Utilities](https://github.com/EtienneLamoureux/durmand-scriptorium/blob/master/docs/UTILITIES.md)
+    - [Localization](https://github.com/EtienneLamoureux/durmand-scriptorium/blob/master/docs/UTILITIES.md#localization)
 
 License
 -------

composer.json

@@ -14,7 +14,8 @@
     ],
     "require": {
 	"guzzlehttp/guzzle": "~5.0",
-	"crystalgorithm/php-json-iterator": "0.1.0-alpha2"
+	"crystalgorithm/php-json-iterator": "0.1.0-alpha2",
+	"myclabs/php-enum": "1.2.1"
     },
     "require-dev": {
 	"phpunit/phpunit": "~4.2",
@@ -27,7 +28,7 @@
     },
     "extra": {
 	"branch-alias": {
-	    "dev-master": "1.1.x-dev"
+	    "dev-master": "1.2.x-dev"
 	}
     }
 }

docs/COLLECTION_CONSUMER.md

@@ -1,5 +1,5 @@
 Collection consumer
-===================
+===
 The collection consumer is used to interact with collection-type endpoints.
 
 Each method below returns a PHP array equivalent to the JSON data returned by the API, unless stated otherwise.

docs/CONVERTER_CONSUMER.md

@@ -1,5 +1,5 @@
 Converter consumer
-===================
+===
 The converter consumer is used to interact with converter-type endpoints.
 
 Each method below returns a PHP array equivalent to the JSON data returned by the API.

docs/SUPPORTED_ENDPOINTS.md

@@ -1,5 +1,5 @@
 Supported endpoints
-===================
+===
 This is a list of the [Guild Wars 2 API](http://wiki.guildwars2.com/wiki/API:Main) endpoints currently supported by Durmand Scriptorium. If a resource is accessible by more than one version of the API, the latest is used whenever possible.
 
 Quaggans

docs/UTILITIES.md

@@ -0,0 +1,43 @@
+Utilities
+===
+Utilities are miscellaneous functionalities provided by Durmand Scriptorium to get the most out of the Guild Wars 2 API.
+
+Localization
+---
+### Definition
+```php
+public function setLocale($localeCode)
+```
+
+The localization utilities populate the information coming from the API with strings translated in the specified locale.  The default locale is English. For a complete list of the supported ISO 639-1 codes to pass to this function, see *Crystalgorithm\DurmandScriptorium\utils\Locale*.
+
+### Supported locales
+- English
+- Español
+- Deutsch
+- Français
+- 한국어 (Hangugeo)
+- 中文 (Zhōngwén)
+
+### Example
+```php
+<?php
+
+use Crystalgorithm\DurmandScriptorium\Facade as DurmandScriptorium;
+use Crystalgorithm\DurmandScriptorium\utils\Locale;
+
+require 'vendor/autoload.php';
+
+// Setup initial locale to use for all API calls
+// Those two lines are equivalent
+$api = new DurmandScriptorium(Locale::FRENCH);
+$api = new DurmandScriptorium('fr'); // ISO 639-1 code
+
+// You can also change the locale on the fly
+// Again, both these lines are equivalent
+$api->setLocale(Locale::GERMAN);
+$api->setLocale('de'); // ISO 639-1 code
+```
+###Throws
+*UnexpectedValueException* if given an unsupported locale code
+

src/Facade.php

@@ -8,6 +8,7 @@
 namespace Crystalgorithm\DurmandScriptorium;
 
 use Crystalgorithm\DurmandScriptorium\utils\BatchRequestManager;
+use Crystalgorithm\DurmandScriptorium\utils\Locale;
 use Crystalgorithm\DurmandScriptorium\utils\Settings;
 use Crystalgorithm\DurmandScriptorium\v2\collection\PaginatedCollectionConsumer;
 use Crystalgorithm\DurmandScriptorium\v2\collection\PaginatedCollectionRequestFactory;
@@ -49,8 +50,10 @@ class Facade
      */
     protected $gems;
 
-    public function __construct()
+    public function __construct($localeCode = Locale::ENGLISH)
     {
+	$this->setLocale($localeCode);
+
 	$client = new Client();
 
 	$batchRequestManager = new BatchRequestManager($client);
@@ -65,7 +68,7 @@ public function __construct()
 	$pricesRequestFactory = new PaginatedCollectionRequestFactory($client, Settings::PRICES_ENDPOINT);
 	$this->prices = new PaginatedCollectionConsumer($client, $pricesRequestFactory, $batchRequestManager, $jsonIteratorFactory, 'id');
 
-	$itemsRequestFactory = new PaginatedCollectionRequestFactory($client, Settings::ITEMS_ENDPOINT);
+	$itemsRequestFactory = new PaginatedCollectionRequestFactory($client, Settings::ITEMS_ENDPOINT, true);
 	$this->items = new PaginatedCollectionConsumer($client, $itemsRequestFactory, $batchRequestManager, $jsonIteratorFactory, 'name');
 
 	$coinsRequestFactory = new ConverterRequestFactory($client, Settings::COINS_ENDPOINT);
@@ -123,4 +126,15 @@ public function gems()
 	return $this->gems;
     }
 
+    /**
+     * @param string $localeCode ISO 639-1 locale code
+     * @see Locale
+     * @throws \UnexpectedValueException if given an unsupported locale code
+     */
+    public function setLocale($localeCode)
+    {
+	$locale = new Locale($localeCode);
+	Settings::$LOCALE = $locale->getValue();
+    }
+
 }

src/utils/Locale.php

@@ -0,0 +1,48 @@
+<?php
+
+/*
+ * @author Etienne Lamoureux <etienne.lamoureux@crystalgorithm.com>
+ * @copyright 2014 Etienne Lamoureux
+ * @license http://opensource.org/licenses/BSD-3-Clause BSD-3-Clause
+ */
+namespace Crystalgorithm\DurmandScriptorium\utils;
+
+use MyCLabs\Enum\Enum;
+
+/**
+ * ISO 639-1 locales supported by the GW2 API
+ */
+class Locale extends Enum
+{
+
+    /**
+     * English
+     */
+    const ENGLISH = 'en';
+
+    /**
+     * Español
+     */
+    const SPANISH = 'es';
+
+    /**
+     * Deutsch
+     */
+    const GERMAN = 'de';
+
+    /**
+     * Français
+     */
+    const FRENCH = 'fr';
+
+    /**
+     * 한국어 (Hangugeo)
+     */
+    const KOREAN = 'ko';
+
+    /**
+     * 中文; Zhōngwén
+     */
+    const CHINESE = 'zh';
+
+}

src/utils/Settings.php

@@ -19,6 +19,7 @@ class Settings
     const ID = 'id';
     const IDS = 'ids';
     const PAGE = 'page';
+    const LANG = 'lang';
     const ID_SEPARATOR = ',';
     const PAGE_SIZE = 'page_size';
     const QUANTITY = 'quantity';
@@ -33,5 +34,6 @@ class Settings
     const COINS_ENDPOINT = '/v2/commerce/exchange/coins';
 
     public static $CREATE_REQUEST_OPTIONS = ['verify' => false];
+    public static $LOCALE;
 
 }

src/v2/RequestFactory.php

@@ -14,16 +14,18 @@ abstract class RequestFactory
 {
 
     protected $ENDPOINT_URL = '';
+    protected $supportsLocalization;
 
     /**
      * @var Client
      */
     protected $client;
 
-    public function __construct(Client $client, $endpointUrl)
+    public function __construct(Client $client, $endpointUrl, $supportsLocalization = false)
     {
 	$this->client = $client;
 	$this->ENDPOINT_URL = $endpointUrl;
+	$this->supportsLocalization = $supportsLocalization;
     }
 
     public function baseRequest()
@@ -35,7 +37,15 @@ public function baseRequest()
 
     protected function buildBaseRequest()
     {
-	return $this->client->createRequest(Settings::GET, Settings::BASE_URL . $this->ENDPOINT_URL, Settings::$CREATE_REQUEST_OPTIONS);
+	$request = $this->client->createRequest(Settings::GET, Settings::BASE_URL . $this->ENDPOINT_URL, Settings::$CREATE_REQUEST_OPTIONS);
+
+	if ($this->supportsLocalization)
+	{
+	    $query = $request->getQuery();
+	    $query->set(Settings::LANG, Settings::$LOCALE);
+	}
+
+	return $request;
     }
 
 }