From 23e3138de6fe3f1d24ab3ff6e2ef92474e05c8d2 Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 16:21:32 +0200 Subject: [PATCH 1/8] Update geo data --- src/GeoData.php | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/GeoData.php b/src/GeoData.php index ae172ab..8e30423 100644 --- a/src/GeoData.php +++ b/src/GeoData.php @@ -15,18 +15,17 @@ class GeoData static public $list = [ 'eu' => [ 'en_gb', - 'de_de', 'es_es', 'fr_fr', - 'it_it', - 'pl_pl', - 'pt_pt', 'ru_ru', + 'de_de', + 'pt_pt', + 'it_it', ], 'us' => [ 'en_us', - 'pt_br', 'es_mx', + 'pt_br', ], 'kr' => [ 'ko_kr', @@ -34,8 +33,8 @@ class GeoData 'tw' => [ 'zh_tw', ], - 'sea' => [ - 'en_us', + 'cn' => [ + 'zh_cn', ], ]; } From 0e86a65906679d0e746a3099d0913332e9fd1777 Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 16:28:05 +0200 Subject: [PATCH 2/8] Update way of accessing Blizzard API data --- src/BlizzardClient.php | 125 ++++++++++++++++++---------------------- src/Service/OAuth.php | 41 +++++++++++++ src/Service/Service.php | 45 ++++++++++++--- 3 files changed, 135 insertions(+), 76 deletions(-) create mode 100644 src/Service/OAuth.php diff --git a/src/BlizzardClient.php b/src/BlizzardClient.php index 3f7a374..4959243 100644 --- a/src/BlizzardClient.php +++ b/src/BlizzardClient.php @@ -2,8 +2,8 @@ namespace BlizzardApi; +use BlizzardApi\Service\OAuth; use BlizzardApi\Tokens\Access; -use GuzzleHttp\Client; use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException; use Symfony\Component\OptionsResolver\OptionsResolver; @@ -15,7 +15,8 @@ */ class BlizzardClient { - const API_URL_PATTERN = 'https://region.api.battle.net'; + const API_URL_PATTERN = 'https://region.api.blizzard.com'; + const CHINA_API_URL = 'https://gateway.battlenet.com.cn'; const API_ACCESS_TOKEN_URL_PATTERN = 'https://region.battle.net/oauth/token'; /** @@ -29,9 +30,14 @@ class BlizzardClient private $apiAccessTokenUrl; /** - * @var string $apiKey API key + * @var string $clientId Client ID */ - private $apiKey; + private $clientId; + + /** + * @var string $clientSecret Client Secret + */ + private $clientSecret; /** * @var Access[] $accessTokens Access tokens @@ -51,18 +57,18 @@ class BlizzardClient /** * Constructor * - * @param string $apiKey API key - * @param string $apiSecret API Secret key - * @param string $region Region - * @param string $locale Locale + * @param string $clientId Access token + * @param string $clientSecret API Secret key + * @param string $region Region + * @param string $locale Locale */ - public function __construct($apiKey, $apiSecret, $region = 'us', $locale = 'en_us') + public function __construct($clientId, $clientSecret, $region = 'us', $locale = 'en_us') { $options = [ - 'apiKey' => $apiKey, - 'apiSecret' => $apiSecret, - 'region' => strtolower($region), - 'locale' => strtolower($locale), + 'clientId' => $clientId, + 'clientSecret' => $clientSecret, + 'region' => strtolower($region), + 'locale' => strtolower($locale), ]; $resolver = new OptionsResolver(); @@ -70,8 +76,8 @@ public function __construct($apiKey, $apiSecret, $region = 'us', $locale = 'en_u $options = $resolver->resolve($options); - $this->apiKey = $options['apiKey']; - $this->apiSecret = $options['apiSecret']; + $this->clientId = $options['clientId']; + $this->clientSecret = $options['clientSecret']; $this->region = $options['region']; $this->locale = $options['locale']; @@ -100,49 +106,49 @@ public function getApiAccessTokenUrl() } /** - * Get api key + * Get client ID * - * @return string Api key + * @return string Client ID */ - public function getApiKey() + public function getClientId() { - return $this->apiKey; + return $this->clientId; } /** - * Set api key + * Set client ID * - * @param string $apiKey Api key + * @param string $clientId Client ID * * @return $this */ - public function setApiKey($apiKey) + public function setClientId($clientId) { - $this->apiKey = $apiKey; + $this->clientId = $clientId; return $this; } /** - * Get api secret + * Get client secret * - * @return string Api secret + * @return string Client secret */ - public function getApiSecret() + public function getClientSecret() { - return $this->apiSecret; + return $this->clientSecret; } /** - * Set api secret + * Set client secret * - * @param string $apiSecret Api secret + * @param string $clientSecret Client secret * * @return $this */ - public function setApiSecret($apiSecret) + public function setClientSecret($clientSecret) { - $this->apiSecret = $apiSecret; + $this->clientSecret = $clientSecret; return $this; } @@ -154,7 +160,7 @@ public function setApiSecret($apiSecret) */ public function getRegion() { - return strtolower($this->region); + return $this->region; } /** @@ -181,7 +187,7 @@ public function setRegion($region) */ public function getLocale() { - return strtolower($this->locale); + return $this->locale; } /** @@ -202,6 +208,9 @@ public function setLocale($locale) * Get access token * * @return null|string Access token + * + * @throws \BlizzardApi\Tokens\Exceptions\Expired + * @throws \HttpResponseException */ public function getAccessToken() { @@ -210,7 +219,9 @@ public function getAccessToken() } if (!array_key_exists($this->getRegion(), $this->accessTokens)) { - $this->accessTokens[$this->getRegion()] = $this->requestAccessToken(); + $oauth = new OAuth($this); + + $this->accessTokens[$this->getRegion()] = $oauth->requestAccessToken(); } return $this->accessTokens[$this->getRegion()]->getToken(); @@ -241,7 +252,11 @@ public function setAccessToken(Access $accessToken) */ private function updateApiUrl($region) { - $this->apiUrl = str_replace('region', strtolower($region), self::API_URL_PATTERN); + if ($region === 'cn') { + $this->apiUrl = self::CHINA_API_URL; + } else { + $this->apiUrl = str_replace('region', strtolower($region), self::API_URL_PATTERN); + } return $this; } @@ -284,38 +299,12 @@ private function configureOptions(OptionsResolver $resolver, $region) ); } - $resolver->setRequired(['apiKey', 'apiSecret', 'region', 'locale']) - ->setAllowedTypes('apiKey', 'string') - ->setAllowedTypes('apiSecret', 'string') - ->setAllowedTypes('region', 'string') - ->setAllowedValues('region', array_keys(GeoData::$list)) - ->setAllowedTypes('locale', 'string') - ->setAllowedValues('locale', $locales); - } - - /** - * Request an Access Token from Blizzard - * - * @return Access - * - * @throws \HttpResponseException - */ - protected function requestAccessToken() - { - $options = [ - 'form_params' => [ - 'grant_type' => 'client_credentials', - 'client_id' => $this->getApiKey(), - 'client_secret' => $this->getApiSecret(), - ], - ]; - - $result = (new Client())->post($this->getApiAccessTokenUrl(), $options); - - if (200 === $result->getStatusCode()) { - return Access::fromJson(json_decode($result->getBody()->getContents())); - } else { - throw new \HttpResponseException('Invalid Response'); - } + $resolver->setRequired(['clientId', 'clientSecret', 'region', 'locale']) + ->setAllowedTypes('clientId', 'string') + ->setAllowedTypes('clientSecret', 'string') + ->setAllowedTypes('region', 'string') + ->setAllowedValues('region', array_keys(GeoData::$list)) + ->setAllowedTypes('locale', 'string') + ->setAllowedValues('locale', $locales); } } diff --git a/src/Service/OAuth.php b/src/Service/OAuth.php new file mode 100644 index 0000000..13ee574 --- /dev/null +++ b/src/Service/OAuth.php @@ -0,0 +1,41 @@ + [$this->blizzardClient->getClientId(), $this->blizzardClient->getClientSecret()], + 'form_params' => [ + 'grant_type' => $grantType, + ], + ]; + + $result = (new Client())->post($this->blizzardClient->getApiAccessTokenUrl(), $options); + + if (200 === $result->getStatusCode()) { + return Access::fromJson(json_decode($result->getBody()->getContents())); + } else { + throw new \HttpResponseException('Invalid Response'); + } + } +} diff --git a/src/Service/Service.php b/src/Service/Service.php index dd3d8da..aeb548e 100644 --- a/src/Service/Service.php +++ b/src/Service/Service.php @@ -49,13 +49,13 @@ protected function request($urlSuffix, array $options) 'base_uri' => $this->blizzardClient->getApiUrl(), ]); - $options = $this->generateQueryOptions($options); + $options = $this->generateRequestOptions($options); return $client->get($this->serviceParam.$urlSuffix, $options); } /** - * Generate query options + * Generate request options * * Setting default option to given options array if it does have 'query' key, * otherwise creating 'query' key with default options @@ -64,17 +64,33 @@ protected function request($urlSuffix, array $options) * * @return array */ - private function generateQueryOptions(array $options = []) + private function generateRequestOptions(array $options = []) { - if (isset($options['query'])) { - $result = $options['query'] + $this->getDefaultOptions(); + $result = []; + + if (isset($options['query']) || isset($options['headers'])) { + if (isset($options['query'])) { + $result['query'] = $options['query'] + $this->getQueryDefaultOptions(); + } + + if (isset($options['headers'])) { + $result['headers'] = $options['headers'] + $this->getHeadersDefaultOptions(); + } } else { - $result['query'] = $options + $this->getDefaultOptions(); + $result = $options + $this->getDefaultRequestOptions(); } return $result; } + private function getDefaultRequestOptions() + { + return [ + 'query' => $this->getQueryDefaultOptions(), + 'headers' => $this->getHeadersDefaultOptions(), + ]; + } + /** * Get default options * @@ -82,11 +98,24 @@ private function generateQueryOptions(array $options = []) * * @return array */ - private function getDefaultOptions() + private function getQueryDefaultOptions() { return [ 'locale' => $this->blizzardClient->getLocale(), - 'apiKey' => $this->blizzardClient->getApiKey(), + ]; + } + + /** + * Get headers default options + * + * Get default headers options from configured Blizzard Client + * + * @return array + */ + private function getHeadersDefaultOptions() + { + return [ + 'authorization' => 'bearer '.$this->blizzardClient->getAccessToken(), ]; } } From 2cc9afeeb1bcec359cd0022d203a52d3a7385269 Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 16:40:29 +0200 Subject: [PATCH 3/8] Fix generating request parameters --- src/Service/Service.php | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/Service/Service.php b/src/Service/Service.php index aeb548e..b4e4012 100644 --- a/src/Service/Service.php +++ b/src/Service/Service.php @@ -66,20 +66,26 @@ protected function request($urlSuffix, array $options) */ private function generateRequestOptions(array $options = []) { - $result = []; + $result = [ + 'query' => [], + 'headers' => [], + ]; if (isset($options['query']) || isset($options['headers'])) { if (isset($options['query'])) { - $result['query'] = $options['query'] + $this->getQueryDefaultOptions(); + $result['query'] += $options['query']; } if (isset($options['headers'])) { - $result['headers'] = $options['headers'] + $this->getHeadersDefaultOptions(); + $result['headers'] += $options['headers']; } } else { $result = $options + $this->getDefaultRequestOptions(); } + $result['query'] += $this->getQueryDefaultOptions(); + $result['headers'] += $this->getHeadersDefaultOptions(); + return $result; } From de72d3d2ad46816035d22d40639f769b808323cf Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 17:22:40 +0200 Subject: [PATCH 4/8] Update examples to refer right parameter names --- docs/examples/CommunityOAuthExample.php | 4 ++-- docs/examples/DiabloExample.php | 4 ++-- docs/examples/GameDataExample.php | 4 ++-- docs/examples/StarcraftExample.php | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/examples/CommunityOAuthExample.php b/docs/examples/CommunityOAuthExample.php index df7d599..cd4c4f3 100644 --- a/docs/examples/CommunityOAuthExample.php +++ b/docs/examples/CommunityOAuthExample.php @@ -3,8 +3,8 @@ // Include composer autoload file require_once __DIR__.'/../../vendor/autoload.php'; -// Create a new Blizzard client with Blizzard API key and secret -$client = new \BlizzardApi\BlizzardClient('apiKey', 'apiSecret'); +// Create a new Blizzard client with registered Blizzard Client ID and Client Secret +$client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new Diablo service with configured Blizzard client $diablo = new \BlizzardApi\Service\Diablo($client); diff --git a/docs/examples/DiabloExample.php b/docs/examples/DiabloExample.php index 1562ab2..fc9b2e0 100644 --- a/docs/examples/DiabloExample.php +++ b/docs/examples/DiabloExample.php @@ -3,8 +3,8 @@ // Include composer autoload file require_once __DIR__.'/../../vendor/autoload.php'; -// Create a new Blizzard client with Blizzard API key and secret -$client = new \BlizzardApi\BlizzardClient('apiKey', 'apiSecret'); +// Create a new Blizzard client with registered Blizzard Client ID and Client Secret +$client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new Diablo service with configured Blizzard client $diablo = new \BlizzardApi\Service\Diablo($client); diff --git a/docs/examples/GameDataExample.php b/docs/examples/GameDataExample.php index 69b2978..7fb66f7 100644 --- a/docs/examples/GameDataExample.php +++ b/docs/examples/GameDataExample.php @@ -3,8 +3,8 @@ // Include composer autoload file require_once __DIR__.'/../../vendor/autoload.php'; -// Create a new Blizzard client with Blizzard API key and secret -$client = new \BlizzardApi\BlizzardClient('apiKey', 'apiSecret'); +// Create a new Blizzard client with registered Blizzard Client ID and Client Secret +$client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new GameData service with configured Blizzard client $gameData = new \BlizzardApi\Service\GameData($client); diff --git a/docs/examples/StarcraftExample.php b/docs/examples/StarcraftExample.php index 69fd54b..b9b304c 100644 --- a/docs/examples/StarcraftExample.php +++ b/docs/examples/StarcraftExample.php @@ -3,8 +3,8 @@ // Include composer autoload file require_once __DIR__.'/../../vendor/autoload.php'; -// Create a new Blizzard client with Blizzard API key and secret -$client = new \BlizzardApi\BlizzardClient('apiKey', 'apiSecret'); +// Create a new Blizzard client with registered Blizzard Client ID and Client Secret +$client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new Starcraft service with configured Blizzard client $starcraft = new \BlizzardApi\Service\Starcraft($client); From 98984ebe8363483910b0641e116b4aebebba18b9 Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 17:23:08 +0200 Subject: [PATCH 5/8] Update World of Warcraft API documentation and methods --- docs/examples/WorldOfWarcraftExample.php | 8 +- src/Service/WorldOfWarcraft.php | 306 +++++++++++++++-------- 2 files changed, 200 insertions(+), 114 deletions(-) diff --git a/docs/examples/WorldOfWarcraftExample.php b/docs/examples/WorldOfWarcraftExample.php index 460a4d6..96b8317 100644 --- a/docs/examples/WorldOfWarcraftExample.php +++ b/docs/examples/WorldOfWarcraftExample.php @@ -3,16 +3,14 @@ // Include composer autoload file require_once __DIR__.'/../../vendor/autoload.php'; -// Create a new Blizzard client with Blizzard API key and secret -$client = new \BlizzardApi\BlizzardClient('apiKey', 'apiSecret'); +// Create a new Blizzard client with registered Blizzard Client ID and Client Secret +$client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new World Of Warcraft service with configured Blizzard client $wow = new \BlizzardApi\Service\WorldOfWarcraft($client); // Use API method for getting specific data -$response = $wow->getGuild('test-realm', 'test-guild', [ - 'fields' => 'achievements,challenge', -]); +$response = $wow->getGuildProfile('test-realm', 'test-guild', implode(',', ['achievements', 'challenge'])); // Accessing response status code $response->getStatusCode(); diff --git a/src/Service/WorldOfWarcraft.php b/src/Service/WorldOfWarcraft.php index c23a96f..36e0b6a 100644 --- a/src/Service/WorldOfWarcraft.php +++ b/src/Service/WorldOfWarcraft.php @@ -21,9 +21,9 @@ class WorldOfWarcraft extends Service /** * Get achievement information by ID * - * This provides data about an individual achievement + * Returns data about an individual achievement. * - * @param int $achievementId The ID of the achievement to retrieve + * @param int $achievementId The ID of the achievement to retrieve. * @param array $options Options * * @return ResponseInterface @@ -40,13 +40,13 @@ public function getAchievement($achievementId, array $options = []) /** * Get auction data status * - * Auction APIs currently provide rolling batches of data about current auctions. Fetching auction dumps is a two - * step process that involves checking a per-realm index file to determine if a recent dump has been generated and - * then fetching the most recently generated dump file if necessary. + * Auction APIs currently provide rolling batches of data about current auctions. + * Fetching auction dumps is a two-step process that involves checking a per-realm index file to determine + * if a recent dump has been generated and then fetching the most recently generated dump file (if necessary). * - * This API resource provides a per-realm list of recently generated auction house data dumps + * This API resource provides a per-realm list of recently generated auction house data dumps. * - * @param string $realm The realm being requested + * @param string $realm The realm to request. * @param array $options Options * * @return ResponseInterface @@ -63,8 +63,8 @@ public function getAuctionDataStatus($realm, array $options = []) /** * Get boss master list * - * A list of all supported bosses. A 'boss' in this context should be considered a boss encounter, which may include - * more than one NPC. + * Returns a list of all supported bosses. + * A "boss" in this context should be considered a boss encounter, which may include more than one NPC. * * @param array $options Options * @@ -78,10 +78,10 @@ public function getBossMasterList(array $options = []) /** * Get boss information by ID * - * The boss API provides information about bosses. A 'boss' in this context should be considered a boss encounter, - * which may include more than one NPC. + * The boss API provides information about bosses. + * A "boss" in this context should be considered a boss encounter, which may include more than one NPC. * - * @param int $bossId The ID of the boss you want to retrieve + * @param int $bossId The ID of the boss to retrieve. * @param array $options Options * * @return ResponseInterface @@ -98,12 +98,12 @@ public function getBoss($bossId, array $options = []) /** * Get realm leaderboards * - * The data in this request has data for all 9 challenge mode maps (currently). The map field includes the current - * medal times for each dungeon. Inside each ladder we provide data about each character that was part of each run. - * The character data includes the current cached spec of the character while the member field includes the spec of - * the character during the challenge mode run. + * The request returns data for all nine challenge mode maps (currently). The map field includes the current + * medal times for each dungeon. Each ladder provides data about each character that was part of each run. + * The character data includes the current cached specialization of the character while the member field includes + * the specialization of the character during the challenge mode run. * - * @param string $realm The realm being requested + * @param string $realm The realm to request. * @param array $options Options * * @return ResponseInterface @@ -117,7 +117,7 @@ public function getRealmLeaderboard($realm, array $options = []) * Get region leaderboards * * The region leaderboard has the exact same data format as the realm leaderboards except there is no realm field. - * It is simply the top 100 results gathered for each map for all of the available realm leaderboards in a region. + * Instead, the response has the top 100 results gathered for each map for all of the available realm leaderboards in a region. * * @param array $options Options * @@ -125,7 +125,7 @@ public function getRealmLeaderboard($realm, array $options = []) */ public function getRegionLeaderboard(array $options = []) { - return $this->request('/challenge/region/', $options); + return $this->request('/challenge/region', $options); } // endregion Challenge Mode API @@ -135,20 +135,73 @@ public function getRegionLeaderboard(array $options = []) /** * Get character * - * The Character Profile API is the primary way to access character information. This Character Profile API can be - * used to fetch a single character at a time through an HTTP GET request to a URL describing the character profile - * resource. By default, a basic dataset will be returned and with each request and zero or more additional fields - * can be retrieved. To access this API, craft a resource URL pointing to the character who's information is to be - * retrieved + * The Character Profile API is the primary way to access character information. This API can be used to fetch a single + * character at a time through an HTTP GET request to a URL describing the character profile resource. + * By default, these requests return a basic dataset, and each request can return zero or more additional fields. + * To access this API, craft a resource URL pointing to the desired character for which to retrieve information. + * + * List of possible values in '$fields' variable: + * - '' - Returns a basic dataset of character data. + * - 'achievements' - Returns a list of the battle pets the character has obtained. + * - 'appearance' - Data about the character's current battle pet slots. + * + * The response contains which slot a pet is + * in and whether the slot is empty or locked. The response also includes the battlePetId, which is unique for the + * character and can be used to match a battlePetId in the pets field for the character. The ability list is the + * list of three active abilities on a pet. If the pet is not high enough level for multiple abilities it will always + * be the pet's first three abilities. + * - 'feed' - Returns a list of the character's professions. Does not include class professions. + * - 'guild' - A summary of the guild to which the character belongs. If the character does not belong to a guild and this field is + * requested, this field will not be exposed. + * + * When a guild is requested, this resource returns a map with key-value pairs that describe a basic set of guild + * information. Note that the rank of the character is not included in this block as it describes a guild and not + * a membership of the guild. To retrieve the character's rank within the guild, make a specific, separate request to the guild + * profile resource. + * - 'hunterPets' - Returns a list of all combat pets the character has obtained. + * - 'items' - Returns a list of items equipped by the character. Use of this field will also include the average item level + * and average item level equipped for the character. + * + * When the items field is used, this resource returns a map structure containing information about the character's + * equipped items as well as their average item level. + * - 'mounts' - Returns a list of all mounts the character has obtained. + * - 'pets' - Returns a list of the battle pets the character has obtained. + * - 'petSlots' - Data about the character's current battle pet slots. + * + * The response contains which slot a pet is in and whether the slot is empty or locked. The response also includes + * the battlePetId, which is unique for the character and can be used to match a battlePetId in the pets field for + * the character. The ability list is the list of three active abilities on a pet. If the pet is not high enough + * level for multiple abilities it will always be the pet's first three abilities. + * - 'professions' - Returns a list of the character's professions. Does not include class professions. + * - 'progression' - Returns a list of raids and bosses indicating raid progression and completeness. + * - 'pvp' - Returns a map of PvP information, including arena team membership and rated battlegrounds information. + * - 'quests' - Returns a list of quests the character has completed. + * - 'reputation' - Returns a list of the factions with which the character has an associated reputation. + * - 'statistics' - Returns a map of character statistics. + * - 'stats' - Returns a map of character attributes and stats. + * - 'talents' - Returns a list of the character's talent structures. + * - 'titles' - Returns a list of titles the character has obtained, including the currently selected title. + * - 'audit' - Raw character audit data that powers the character audit on the game site. * * @param string $realm The character's realm. Can be provided as the proper realm name or the normalized realm name * @param string $characterName The name of the character you want to retrieve + * @param string $fields List of character fields separated by comma (f.e. 'items,mounts,pets,guild') * @param array $options Options * * @return ResponseInterface */ - public function getCharacter($realm, $characterName, array $options = []) + public function getCharacter($realm, $characterName, $fields = '', array $options = []) { + $fieldsQueryParam = [ + 'fields' => $fields, + ]; + + if (isset($options['query'])) { + $options['query'] += $fieldsQueryParam; + } else { + $options['query'] = $fieldsQueryParam; + } + return $this->request('/character/'.(string) $realm.'/'.(string) $characterName, $options); } @@ -159,22 +212,50 @@ public function getCharacter($realm, $characterName, array $options = []) /** * Get guild profile * - * The guild profile API is the primary way to access guild information. This guild profile API can be used to fetch - * a single guild at a time through an HTTP GET request to a url describing the guild profile resource. By default, - * a basic dataset will be returned and with each request and zero or more additional fields can be retrieved. - * - * There are no required query string parameters when accessing this resource, although the fields query string - * parameter can optionally be passed to indicate that one or more of the optional datasets is to be retrieved. - * Those additional fields are listed in the method titled "Optional Fields". + * The guild profile API is the primary way to access guild information. This API can fetch a single guild at a time through + * an HTTP GET request to a URL describing the guild profile resource. By default, these requests return a basic dataset and + * each request can retrieve zero or more additional fields. + * + * Although this endpoint has no required query string parameters, requests can optionally pass the fields query string parameter + * to indicate that one or more of the optional datasets is to be retrieved. Those additional fields are listed in the method + * titled "Optional Fields". + * + * List of possible values in '$fields' variable: + * - '' - Returns a basic guild data. + * - 'members' - A value of members tells the API to include guild's member list in the response. + * - 'achievements' - A set of data structures that describe the achievements earned by the guild. + * When requesting achievement data, several sets of data will be returned. + * + * - **achievementsCompleted** : a list of achievement IDs. + * - **achievementsCompletedTimestamp**: a list of timestamps corresponding to the achievement IDs in the **achievementsCompleted** list. The value of each timestamp indicates when the related achievement was earned by the guild. + * - **criteria** : a list of criteria IDs used to determine the partial completeness of guild achievements. + * - **criteriaQuantity** : a list of values associated with a given achievement criteria. The position of a value corresponds to the position of a given achievement criteria. + * - **criteriaTimestamp** : a list of timestamps with values that represent when the criteria was considered complete. The position of a value corresponds to the position of a given achievement criteria. + * - **criteriaCreated** : a list of timestamps for which the value represents the time the criteria was considered started. The position of a value corresponds to the position of a given achievement criteria. + * - 'news' - A set of data structures that describe the guild's news feed. When the news feed is requested, + * this resource returns a list of news objects. Each one has a type, a timestamp, and some other data depending + * on the type: itemId, an achievement object, and so on. + * - 'challenge' - The top three challenge mode guild run times for each challenge mode map. * * @param string $realm The realm the guild lives on * @param string $guildName Name of the guild being queried + * @param string $fields List of guild fields separated by comma (f.e. 'items,mounts,pets,guild') * @param array $options Options * * @return ResponseInterface */ - public function getGuild($realm, $guildName, array $options = []) + public function getGuildProfile($realm, $guildName, $fields = '', array $options = []) { + $fieldsQueryParam = [ + 'fields' => $fields, + ]; + + if (isset($options['query'])) { + $options['query'] += $fieldsQueryParam; + } else { + $options['query'] = $fieldsQueryParam; + } + return $this->request('/guild/'.(string) $realm.'/'.(string) $guildName, $options); } @@ -185,9 +266,9 @@ public function getGuild($realm, $guildName, array $options = []) /** * Get item information by ID * - * The item API provides detailed item information. This includes item set information if this item is part of a set. + * The item API provides detailed item information, including item set information. * - * @param int $itemId Unique ID of the item being requested + * @param int $itemId The requested item's unique ID. * @param array $options Options * * @return ResponseInterface @@ -200,9 +281,9 @@ public function getItem($itemId, array $options = []) /** * Get set information by ID * - * The item API provides detailed item information. This includes item set information if this item is part of a set. + * The item API provides detailed item information, including item set information. * - * @param int $setId Unique ID of the set being requested + * @param int $setId The requested set's unique ID. * @param array $options Options * * @return ResponseInterface @@ -219,7 +300,7 @@ public function getItemSet($setId, array $options = []) /** * Get mount master list * - * A list of all supported mounts + * Returns a list of all supported mounts. * * @param array $options Options * @@ -235,26 +316,25 @@ public function getMountMasterList(array $options = []) // region Pet API /** - * Get pet lists + * Get pet master lists * - * A list of all supported battle and vanity pets + * Returns a list of all supported battle and vanity pets. * * @param array $options Options * * @return ResponseInterface */ - public function getPetList(array $options = []) + public function getPetMasterList(array $options = []) { return $this->request('/pet/', $options); } /** - * Get pet ability information by ID + * Get pet ability by ID * - * This provides data about a individual battle pet ability ID. We do not provide the tooltip for the ability yet. - * We are working on a better way to provide this since it depends on your pet's species, level and quality rolls. + * Returns data about a individual battle pet ability ID. This resource does not provide ability tooltips. * - * @param int $abilityId The ID of the ability you want to retrieve + * @param int $abilityId The ID of the ability to retrieve. * @param array $options Options * * @return ResponseInterface @@ -265,12 +345,12 @@ public function getPetAbility($abilityId, array $options = []) } /** - * Get pet species information by ID + * Get pet species by ID * - * This provides the data about an individual pet species. The species IDs can be found your character profile - * using the options pets field. Each species also has data about what it's 6 abilities are. + * Returns data about an individual pet species. Use pets as the field value in a character profile request to get species IDs. + * Each species also has data about its six abilities. * - * @param int $speciesId The species you want to retrieve data on + * @param int $speciesId The species for which to retrieve data. * @param array $options Options * * @return ResponseInterface @@ -281,17 +361,41 @@ public function getPetSpecies($speciesId, array $options = []) } /** - * Get pet stats by species ID + * Get pet stats by ID * - * Retrieve detailed information about a given species of pet + * Returns detailed information about a given species of pet. * - * @param int $speciesId The pet's species ID. This can be found by querying a users' list of pets via the Character Profile API + * @param int $speciesId The pet's species ID. This can be found by querying a user's list of pets via the Character Profile API. + * @param int $level (optional) The pet's level. Pet levels max out at 25. If omitted, the API assumes a default value of 1. + * @param int $breedId (optional) The pet's breed. Retrievable via the Character Profile API. If omitted the API assumes a default value of 3. + * @param int $qualityId (optional) The pet's quality. Retrievable via the Character Profile API. Pet quality can range from 0 to 5 + * (0 is poor quality and 5 is legendary). If omitted, the API will assume a default value of 1. * @param array $options Options * * @return ResponseInterface */ - public function getPetStats($speciesId, array $options = []) + public function getPetStats($speciesId, $level = null, $breedId = null, $qualityId = null, array $options = []) { + $queryParams = []; + + if ($level !== null) { + $queryParams['level'] = $level; + } + if ($breedId !== null) { + $queryParams['breedId'] = $breedId; + } + if ($qualityId !== null) { + $queryParams['qualityId'] = $qualityId; + } + + if (isset($options['query'])) { + $options['query'] += $queryParams; + } else { + $options['query'] = $queryParams; + } + + var_dump($options); + return $this->request('/pet/stats/'.(int) $speciesId, $options); } @@ -302,10 +406,9 @@ public function getPetStats($speciesId, array $options = []) /** * Get leaderboards * - * The Leaderboard API endpoint provides leaderboard information for the 2v2, 3v3, 5v5 and Rated Battleground - * leaderboards. + * The Leaderboard API endpoint provides leaderboard information for the 2v2, 3v3, 5v5, and Rated Battleground leaderboards. * - * @param int $bracket The type of leaderboard you want to retrieve. Valid entries are 2v2, 3v3, 5v5, and rbg + * @param int $bracket The type of leaderboard to retrieve. Valid entries are **2v2**, **3v3**, **5v5**, and **rbg**. * @param array $options Options * * @return ResponseInterface @@ -322,9 +425,9 @@ public function getLeaderboards($bracket, array $options = []) /** * Get quest information by ID * - * Retrieve metadata for a given quest. + * Returns metadata for a specified quest. * - * @param int $questId The ID of the desired quest + * @param int $questId The ID of the quest to retrieve. * @param array $options Options * * @return ResponseInterface @@ -341,16 +444,29 @@ public function getQuest($questId, array $options = []) /** * Get realm status * - * The realm status API allows developers to retrieve realm status information. This information is limited to - * whether or not the realm is up, the type and state of the realm, the current population, and the status of the - * two world PvP zones + * The realm status API allows developers to retrieve realm status information. This information is limited to whether or not + * the realm is up, the type and state of the realm, and the current population. * - * @param array $options Options + * Although this endpoint has no required query string parameters, use the optional **realms** parameter to limit the realms + * returned to a specific set of realms. + * + * @param string $realms List of realms separated by comma (f.e. 'greymane,aegwynn') + * @param array $options Options * * @return ResponseInterface */ - public function getRealmStatus(array $options = []) + public function getRealmStatus($realms = '', array $options = []) { + $queryParams = [ + 'realms' => $realms, + ]; + + if (isset($options['query'])) { + $options['query'] += $queryParams; + } else { + $options['query'] = $queryParams; + } + return $this->request('/realm/status', $options); } @@ -361,9 +477,9 @@ public function getRealmStatus(array $options = []) /** * Get recipe information by ID * - * The recipe API provides basic recipe information + * Returns basic recipe information. * - * @param int $recipeId Unique ID for the desired recipe + * @param int $recipeId Unique ID for the desired recipe. * @param array $options Options * * @return ResponseInterface @@ -380,9 +496,9 @@ public function getRecipe($recipeId, array $options = []) /** * Get spell information by ID * - * The spell API provides some information about spells + * Returns information about spells. * - * @param int $spellId Unique ID of the desired spell + * @param int $spellId The ID of the spell to retrieve. * @param array $options Options * * @return ResponseInterface @@ -399,9 +515,8 @@ public function getSpell($spellId, array $options = []) /** * Get zone master list * - * A list of all supported zones and their bosses. A 'zone' in this context should be considered a dungeon, or a - * raid, not a zone as in a world zone. A 'boss' in this context should be considered a boss encounter, which may - * include more than one NPC. + * Returns a list of all supported zones and their bosses. A "zone" in this context should be considered a dungeon or a raid, not + * a world zone. A "boss" in this context should be considered a boss encounter, which may include more than one NPC. * * @param array $options Options * @@ -415,9 +530,9 @@ public function getZonesMasterList(array $options = []) /** * Get zone information by ID * - * The Zone API provides some information about zones. + * Returns information about zones. * - * @param int $zoneId The ID of the zone you want to retrieve + * @param int $zoneId The ID of the zone to retrieve. * @param array $options Options * * @return ResponseInterface @@ -434,7 +549,7 @@ public function getZone($zoneId, array $options = []) /** * Get data battlegroups * - * The battlegroups data API provides the list of battlegroups for this region. Please note the trailing '/' on this URL + * Returns a list of battlegroups for the specified region. Note the trailing / on this request path. * * @param array $options Options * @@ -448,7 +563,7 @@ public function getDataBattlegroups(array $options = []) /** * Get data character races * - * The character races data API provides a list of each race and their associated faction, name, unique ID, and skin + * Returns a list of races and their associated faction, name, unique ID, and skin. * * @param array $options Options * @@ -462,7 +577,7 @@ public function getDataCharacterRaces(array $options = []) /** * Get data character classes * - * The character classes data API provides a list of character classes + * Returns a list of character classes. * * @param array $options Options * @@ -476,8 +591,7 @@ public function getDataCharacterClasses(array $options = []) /** * Get data character achievements * - * The character achievements data API provides a list of all of the achievements that characters can earn as well - * as the category structure and hierarchy + * Returns a list of all achievements that characters can earn as well as the category structure and hierarchy. * * @param array $options Options * @@ -491,7 +605,7 @@ public function getDataCharacterAchievements(array $options = []) /** * Get data guild rewards * - * The guild rewards data API provides a list of all guild rewards + * The guild rewards data API provides a list of all guild rewards. * * @param array $options Options * @@ -505,7 +619,7 @@ public function getDataGuildRewards(array $options = []) /** * Get data guild perks * - * The guild perks data API provides a list of all guild perks + * Returns a list of all guild perks. * * @param array $options Options * @@ -519,8 +633,7 @@ public function getDataGuildPerks(array $options = []) /** * Get data guild achievements * - * The guild achievements data API provides a list of all of the achievements that guilds can earn as well as the - * category structure and hierarchy + * Returns a list of all guild achievements as well as the category structure and hierarchy. * * @param array $options Options * @@ -534,7 +647,7 @@ public function getDataGuildAchievements(array $options = []) /** * Get data item classes * - * The item classes data API provides a list of item classes + * Returns a list of item classes. * * @param array $options Options * @@ -548,7 +661,7 @@ public function getDataItemClasses(array $options = []) /** * Get data talents * - * The talents data API provides a list of talents, specs and glyphs for each class + * Returns a list of talents, specs, and glyphs for each class. * * @param array $options Options * @@ -562,7 +675,7 @@ public function getDataTalents(array $options = []) /** * Get data pet types * - * The different bat pet types (including what they are strong and weak against) + * Returns a list of the different battle pet types, including what they are strong and weak against. * * @param array $options Options * @@ -574,29 +687,4 @@ public function getDataPetTypes(array $options = []) } // endregion Data resources API - - // region Community OAuth API - - /** - * Get profile characters - * - * This provides data about the current logged in OAuth user's WoW profile - * - * @param null|string $accessToken Authorized user access token - * @param array $options Options - * - * @return ResponseInterface - */ - public function getProfileCharacters($accessToken = null, array $options = []) - { - if (null === $accessToken) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - } else { - $options['access_token'] = $accessToken; - } - - return $this->request('/user/characters', $options); - } - - // endregion Community OAuth API } From 146223e0325d008a29fc9476d1468cae9b09568d Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 17:26:45 +0200 Subject: [PATCH 6/8] Rename class GameData to DiabloGameData --- ...DataExample.php => DiabloGameDataExample.php} | 2 +- src/Service/{GameData.php => DiabloGameData.php} | 16 ++-------------- 2 files changed, 3 insertions(+), 15 deletions(-) rename docs/examples/{GameDataExample.php => DiabloGameDataExample.php} (90%) rename src/Service/{GameData.php => DiabloGameData.php} (84%) diff --git a/docs/examples/GameDataExample.php b/docs/examples/DiabloGameDataExample.php similarity index 90% rename from docs/examples/GameDataExample.php rename to docs/examples/DiabloGameDataExample.php index 7fb66f7..a827d0b 100644 --- a/docs/examples/GameDataExample.php +++ b/docs/examples/DiabloGameDataExample.php @@ -7,7 +7,7 @@ $client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new GameData service with configured Blizzard client -$gameData = new \BlizzardApi\Service\GameData($client); +$gameData = new \BlizzardApi\Service\DiabloGameData($client); // Use API method for getting specific data $response = $gameData->getEraLeaderboard(1, 'rift-barbarian'); diff --git a/src/Service/GameData.php b/src/Service/DiabloGameData.php similarity index 84% rename from src/Service/GameData.php rename to src/Service/DiabloGameData.php index 805dc31..7f3160c 100644 --- a/src/Service/GameData.php +++ b/src/Service/DiabloGameData.php @@ -5,11 +5,11 @@ use Psr\Http\Message\ResponseInterface; /** - * GameData class + * Class Diablo Game Data * * @author Oleg Kachinsky */ -class GameData extends Service +class DiabloGameData extends Service { // region Game data API @@ -24,8 +24,6 @@ class GameData extends Service */ public function getSeasonIndex(array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/season/', $options); } @@ -41,8 +39,6 @@ public function getSeasonIndex(array $options = []) */ public function getSeasonById($id, array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/season/'.(int) $id, $options); } @@ -59,8 +55,6 @@ public function getSeasonById($id, array $options = []) */ public function getSeasonLeaderboardById($id, $leaderboard, array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/season/'.(int) $id.'/leaderboard/'.(string) $leaderboard, $options); } @@ -75,8 +69,6 @@ public function getSeasonLeaderboardById($id, $leaderboard, array $options = []) */ public function getEraIndex(array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/era/', $options); } @@ -92,8 +84,6 @@ public function getEraIndex(array $options = []) */ public function getEraIndexById($id, array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/era/'.(int) $id, $options); } @@ -110,8 +100,6 @@ public function getEraIndexById($id, array $options = []) */ public function getEraLeaderboard($id, $leaderboard, array $options = []) { - $options['access_token'] = $this->blizzardClient->getAccessToken(); - return $this->request('/data/d3/era/'.(int) $id.'/leaderboard/'.(string) $leaderboard, $options); } From f6c4255ad40d44ba58825e274b54025d339e66ae Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 17:27:01 +0200 Subject: [PATCH 7/8] Update documentation --- src/Service/CommunityOAuth.php | 2 +- src/Service/OAuth.php | 5 +++++ src/Service/Service.php | 2 +- src/Service/Starcraft.php | 2 +- 4 files changed, 8 insertions(+), 3 deletions(-) diff --git a/src/Service/CommunityOAuth.php b/src/Service/CommunityOAuth.php index 35432bb..322d2cf 100644 --- a/src/Service/CommunityOAuth.php +++ b/src/Service/CommunityOAuth.php @@ -5,7 +5,7 @@ use Psr\Http\Message\ResponseInterface; /** - * Class CommunityOAuth + * Class Community OAuth * * @author Oleg Kachinsky */ diff --git a/src/Service/OAuth.php b/src/Service/OAuth.php index 13ee574..3de60b7 100644 --- a/src/Service/OAuth.php +++ b/src/Service/OAuth.php @@ -5,6 +5,11 @@ use BlizzardApi\Tokens\Access; use GuzzleHttp\Client; +/** + * Class OAuth + * + * @author Oleg Kachinsky + */ class OAuth extends Service { /** diff --git a/src/Service/Service.php b/src/Service/Service.php index b4e4012..90d9960 100644 --- a/src/Service/Service.php +++ b/src/Service/Service.php @@ -7,7 +7,7 @@ use Psr\Http\Message\ResponseInterface; /** - * Class Abstract Service + * Class Service * * @author Oleg Kachinsky */ diff --git a/src/Service/Starcraft.php b/src/Service/Starcraft.php index 0632add..78cee08 100644 --- a/src/Service/Starcraft.php +++ b/src/Service/Starcraft.php @@ -5,7 +5,7 @@ use Psr\Http\Message\ResponseInterface; /** - * Starcraft class + * Class Starcraft * * @author Oleg Kachinsky */ From 82784e26671462f2be1c8131d600c0bc685d6b46 Mon Sep 17 00:00:00 2001 From: Oleg Kachinskyi Date: Sat, 26 Jan 2019 17:28:43 +0200 Subject: [PATCH 8/8] Rename class WorldOfWarcraft to WorldOfWarcraftCommunity --- ...arcraftExample.php => WorldOfWarcraftCommunityExample.php} | 2 +- .../{WorldOfWarcraft.php => WorldOfWarcraftCommunity.php} | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/examples/{WorldOfWarcraftExample.php => WorldOfWarcraftCommunityExample.php} (90%) rename src/Service/{WorldOfWarcraft.php => WorldOfWarcraftCommunity.php} (99%) diff --git a/docs/examples/WorldOfWarcraftExample.php b/docs/examples/WorldOfWarcraftCommunityExample.php similarity index 90% rename from docs/examples/WorldOfWarcraftExample.php rename to docs/examples/WorldOfWarcraftCommunityExample.php index 96b8317..3270765 100644 --- a/docs/examples/WorldOfWarcraftExample.php +++ b/docs/examples/WorldOfWarcraftCommunityExample.php @@ -7,7 +7,7 @@ $client = new \BlizzardApi\BlizzardClient('clientId', 'clientSecret'); // Create a new World Of Warcraft service with configured Blizzard client -$wow = new \BlizzardApi\Service\WorldOfWarcraft($client); +$wow = new \BlizzardApi\Service\WorldOfWarcraftCommunity($client); // Use API method for getting specific data $response = $wow->getGuildProfile('test-realm', 'test-guild', implode(',', ['achievements', 'challenge'])); diff --git a/src/Service/WorldOfWarcraft.php b/src/Service/WorldOfWarcraftCommunity.php similarity index 99% rename from src/Service/WorldOfWarcraft.php rename to src/Service/WorldOfWarcraftCommunity.php index 36e0b6a..cc8614a 100644 --- a/src/Service/WorldOfWarcraft.php +++ b/src/Service/WorldOfWarcraftCommunity.php @@ -5,11 +5,11 @@ use Psr\Http\Message\ResponseInterface; /** - * Class World Of Warcraft + * Class World Of Warcraft Community APIs * * @author Oleg Kachinsky */ -class WorldOfWarcraft extends Service +class WorldOfWarcraftCommunity extends Service { /** * {@inheritdoc}