jamesmcfadden/php-gw2-api

PhpGw2Api is a PHP wrapper for the Guild Wars 2 API

v1.0.0 2014-02-25 17:21 UTC

README

Php-Gw2-Api is a PHP wrapper for the Guild Wars 2 API.

Requirements

  • PHP 5.3+
  • cURL

Installation

Composer

The recommended installation method is through the popular PHP package manager Composer.

Create (or, if you already have one, update) your composer.json file in the root of your application to require the library:

{
    "name": "MyApplication",
    "require": {
        "jamesmcfadden/php-gw2-api": "1.0.0"
    }
}

Run composer install in the root directory of your application.

If you haven't already, include the composer autoload in your application bootstrap/ setup:

// Include Composer autoload.php
require_once '/path/to/vendor/autoload.php';

You're ready to go. To find out more about composer read the docs.

Manual

In the directory you want to install the library to:

git clone git@github.com:jamesmcfadden/Php-Gw2-Api.git php-gw2-api

Require the library:

require_once '/path/to/php-gw2-api/src/PhpGw2Api/Service.php';

Usage

// Instantiate a new service object and specify cache path and TTL settings
$service = new PhpGw2Api\Service(__DIR__ . '/cache', 3600);

// Set how to return the JSON
$service->returnAssoc(true);

// Query 
$items = $service->getItems();

// Play around
$itemId = $items['items'][50];
$item = $service->getItemDetails(array('item_id' => $itemId));

var_dump($item);

Examples

Guild Wars 2 - WvW Matchups Wordpress plugin by Klaufel (implementation example here)

Caching

If a cache directory is specified, the JSON response will be cached locally with the specified lifetime, or a default of 3600 seconds. You can specify cache settings in the following ways:

Upon instantiation:

$service = new PhpGw2Api\Service(__DIR__ . '/cache', 3600);

Using the fluent interface:

$service->setCacheDirectory(__DIR__ . '/cache')
        ->setCacheTtl(120)
        ->getItems();

Additionally, TTL may be specified on a per request basis:

$service->getItems(array(), 60);

Parallel Requests

PhpGw2Api supports HTTP pipelining, meaning that you may make multiple API requests in parallel. This is substantially quicker and more efficient than running multiple requests one after the other.

Here is an example of running multiple requests in parallel:

$service = new PhpGw2Api\Service('.');
$items = $service->getItems();
$details = array();

// Initialise a stack of requests
$service->initStack();

// Each subsequest request will be registered on the stack
foreach($items['items'] as $x => $i) {

	if($x == 1000) {
		break;
	}
	$details[$i] = $service->getItemDetails(array('item_id' => $i));
}

// Execute the stack, retrieving the results
$results = $service->executeStack();

Results are returned as an array, in order of when they were registered on the stack. Note that results returned in this fashion are also cached as would be expected with a single request.

Reference

The following draws reference from https://forum-en.guildwars2.com/forum/community/api/API-Documentation.

EDIT: The above link is soon being deprecated, reference can be found at http://wiki.guildwars2.com/wiki/API

getEvents

Optional parameters: world_id, map_id, event_id

$service->getEvents(array('world_id' => 1001));

getEventNames

Optional parameters: lang

$service->getEventNames(array('lang' => 'fr'));

getEventDetails

Optional parameters: event_id, lang

$service->getEventDetails(array('event_id' => 'EED8A79F-B374-4AE6-BA6F-B7B98D9D7142', 'lang' => 'fr'));

getMapNames

Optional parameters: lang

$service->getMapNames(array('lang' => 'fr'));

getWorldNames

Optional parameters: lang

$service->getWorldNames(array('lang' => 'fr'));

getMatches

$service->getMatches();

getMatchDetails

Requred parameters: match_id

$service->getMatchDetails(array('match_id' => '2-3'));

getObjectiveNames

Optional parameters: lang

$service->getObjectiveNames(array('lang' => 'fr'));

getItems

$service->getItems();

getItemDetails

Required parameters: item_id Optional parameters: lang

$service->getItemDetails(array('item_id' => 15728));

getRecipes

$service->getRecipes();

getRecipeDetails

Required parameters: recipe_id

$service->getRecipeDetails(array('recipe_id' => 984));

getGuildDetails

Required parameters: guild_id or guild_name

$service->getGuildDetails(array('guild_name' => 'In Time'));

getBuild

$service->getBuild();

getColours

Optional parameters: lang

$service->getColours(array('lang' => 'fr'));

getColors

Alias of getColours() for our American friends.

Optional parameters: lang

$service->getColors(array('lang' => 'fr'));

getContinents

Optional parameters: lang

$service->getContinents(array('lang' => 'fr'));

getMaps

Optional parameters: lang, map_id

$service->getMaps(array('lang' => 'fr', 'map_id' => 80));

getMapFloor

Required parameters: continent_id, floor Optional parameters: lang

$service->getMapFloor(array('continent_id' => 1, 'floor' => 1, 'lang' => 'fr'));

getFiles

$service->getFiles();

License

Released under the MIT licence

Feedback & contribution

Feedback and contribution are welcomed!