API PHP Class Extended

From EVEDev
Jump to: navigation, search
Api.pngAPI Resources - Category Home - API Libraries - API Usage Examples - API Method Reference

Contents

The Extended PHP API Class

This class has a basic interface for communicating with the Eve Online API but also offers options for extending this power via a module based system. By programming different modules the class can be extended to perform various actions with the different Eve Online API documents.

Please note that this class has nothing to do with the other API class found on this wiki.

Download

The latest version can be found here:

Download FILE DOES NOT WORK SITE HAS CLOSED!!!!!

This location is subject to change when an official SourceForge project is created.

Usage

Supplied with the standard download is an example script which demonstrates how the class is used:

 
<?php
 
require_once("api/EveAPI.php");
 
try{
	$api = new EveAPI("Some random API Key", "Some random user ID");
 
	print_r($api->characters->getCharacters());
} catch (Exception $e) {
	echo $e->getMessage();
}
 
?>
 

The first thing you must do is of course include the class into your application. Once included you can begin using it. It's important to wrap all code using the API in try/catch tags. Many people are unaware of this statement, but it is a standard programming practice and is always suggested to use in order to make your application easier to debug. The first process is creating the new EveAPI object which consists of supplying an API key and User ID. These two details are used the remainder of the object's life. Next is sample code for using a module. Note that in the supplied download is the file /modules/characters.class.php. This is what we call a "module", or in other words an extension to the class. Every module does a specific task. In this case the characters module handles the /account/Characters.xml.aspx API file by parsing it and returning all characters along with their details in an array. If you open up the /modules/characters.class.php file you will see the following code:

 
<?php
 
/**
 * A module for EveAPI that deals with an accounts characters
 * 
 * @author AliasXNeo (Josh)
 * @package EveAPI
 *
 */
class characters extends moduleTemplate 
{
	private $chars = array();
 
	/**
	 * Class constructor
	 * 
	 * Loads the current characters for the loaded account
	 * into an array
	 *
	 */
	function __construct()
	{
		parent::__construct();
 
		$xml = $this->apiBridge->call("/account/Characters.xml.aspx");
 
		$chars = $xml->result->rowset->row;
 
		foreach($chars as $char)
		{
			$this->chars["{$char['name']}"] = $char;
		}
	}
 
	/**
	 * Returns parsed characters setup in characters::__construct()
	 *
	 * @return Mixed
	 */
	function getCharacters()
	{
		return $this->chars;
	}
}
 
?>
 

As you can see all the loading and parsing is done in the class constructor, which means when it is first called it automatically loads all the character data. It then has a separate function called getCharacters() for retrieving the parsed data.

Returning to the example code we see that the way you access a module is simply by giving it's name as if it were an attribute of the API class. For instance if we had a module named wallet, in order to access it we would simply call $api->wallet->somefunction(). This keeps things simple and clean. To add a new module all you must do is add the php file into the /modules directory. Note that loading a module that does not exist in the /modules directory will result in an error.

Creating Modules

One of the core ideas of this class is modules. By having separate modules users are free to add their own additions to the class without touching the actual class code. It also allows other developers to upload their own modules for less experienced users to use in their own applications. The process of creating a module is very simple.

The first rule you must know is that all modules extend the moduleTemplate class. This class is what essentially ties your module in with the API class. It gives you access to the apiBridge object which contains the necessary functions for making calls to the API. It also gives you user supplied data like the Character ID. Let's take a look at the /modules/characters.class.php file supplied in the download:

 
<?php
 
/**
 * A module for EveAPI that deals with an accounts characters
 * 
 * @author AliasXNeo (Josh)
 * @package EveAPI
 *
 */
class characters extends moduleTemplate 
{
	private $chars = array();
 
	/**
	 * Class constructor
	 * 
	 * Loads the current characters for the loaded account
	 * into an array
	 *
	 */
	function __construct()
	{
		parent::__construct();
 
		$xml = $this->apiBridge->call("/account/Characters.xml.aspx");
 
		$chars = $xml->result->rowset->row;
 
		foreach($chars as $char)
		{
			$this->chars["{$char['name']}"] = $char;
		}
	}
 
	/**
	 * Returns parsed characters setup in characters::__construct()
	 *
	 * @return Mixed
	 */
	function getCharacters()
	{
		return $this->chars;
	}
}
 
?>
 

As we can see the first rule is applied here, the class extends the moduleTemplate class. You might have noticed an important consistency here. The name of the module must be consistent throughout your script. Meaning if your module was named corp then your file must be named corp.class.php and the name of your class must be corp. Disregarding this may result in fatal errors. There is one more mandatory thing in every module and that is the __construct() function. Whether you use it or not you must include it in your class and you must add the parent::__construct() line into it. This basically sets up the parent moduleTemplate class and not calling it will result in a NULL value for the apiBridge object, thus cutting you off from the API class.

Besides those minor requirements the rest of the class is up to you. You may do whatever you please so long as they don't break any of the requirements above. When you have finished the module all you must do is add it to the /modules directory and then call it from the main class. For instance if we just finished the corp module we would add corp.class.php to /modules and then in our application we would call $api->corp->someFunction().

Personal tools