API PHP Class

From EVEDev
Jump to: navigation, search
Api.pngAPI Resources - Category Home - API Libraries - API Usage Examples - API Method Reference
API PHP Class
Maintainer: Ix Forres
Stable release: 1.0
Development release: Halted
OS: Platform independant
License: GNU GPL V3
Website: [http://www.talkunafraid.co.uk

Contents

EVE API Class for PHP5

This is a basic PHP class which should help new PHP developers start working with the API. It requires PHP5 for the SimpleXML class and cURL- you probably have both of these, but if you don't then look elsewhere- if you have PHP5 but not cURL look for the non-cURL version, which may not work under some hosts with the allow_url_fopen option disabled.

Usage

This example demonstrates a basic call to the API which returns the EVE characterID of a character if the character exists in the API specified, or false, and displays a message.

 
$api = new apiinterface();
$api->setup("APIUSERID","APIKEY");
/* 
 * You can also set the two parameters manually, but I prefer having this as a one-liner. 
 * The other way would be:
 * $api->userid = "APIUSERID"
 * $api->apikey = "APIKEY"
 * It's entirely up to you.
 */
$t = $api->isCharInAPI("NAMEOFCHARACTER");
if ($t) { echo "Character exists, EVE Character ID ".$t; } else { echo "Character not in this account"; }
 

The apiRequest function can be used to perform arbitrary requests to any resource on the API. Additional variables can be specified in the array.

You can navigate the object using the XML object- for example:

 
<eveapi version="1">
<currentTime>2007-08-04 00:21:24</currentTime>
<result>
<rowset name="characters" key="characterID" columns="name,characterID,corporationName,corporationID">
<row name="x" characterID="x" corporationName="x" corporationID="x"/>
<row name="x" characterID="x" corporationName="x" corporationID="x"/>
<row name="x" characterID="x" corporationName="x" corporationID="x"/>
</rowset>
</result>
<cachedUntil>2007-08-04 01:21:24</cachedUntil>
</eveapi>
 

To get, say, the corporation name from the first character, we could do this:

 
$api = new apiinterface();
$api->setup("APIUSERID","APIKEY");
$ret = $api->apiRequest("/account/Characters.xml.aspx"); // No array needed, will just provide basic authentication data.
echo "Corporation Name: ".$ret->result->rowset->row[0]['corporationName'];
 

Attributes are associatively stored within an array, multiple XML keys here are indexed numerically, for example rows here.

Credit/License

If you use this class no crediting is required but feel free to do so (to James "Ix Forres" Harrison, http://www.talkunafraid.co.uk/). ISK donations are also much appreciated. This code is GNU GPL V3 licensed- the license is available on their website for viewing.

Download

You can download the latest copy of the class from SVN here: svn://api.eve-metrics.com/trunk/

SVN Currently Unavaliable

Error: Can't connect to host 'api.eve-metrics.com': No connection could be made because the target machine actively refused it.

Alternatively, grab the api.php source from below. You can build documentation for the class with PHPdoc.

The class

 
<?php
/* File: api.php
 * Created on 7 Aug 2007
 * EVE API PHP Class Project
 * Created by James Harrison (Ix Forres)
 * @version 1.0
 * @package EVEAPI
 * 
 * Documentation and homepage at http://api.eve-metrics.com/
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * I recommend you enable the following two lines to catch errors.
 * I strongly recommend you disable the ini value 'display_errors' and set error 
 * reporting to E_NONE for production environments to avoid data exposure.
 * 
 * error_reporting(E_ALL);
 * ini_set("display_errors","true");
 */
class apiinterface {
	/*
	 * EVE API UserID. Passed with all requests.
	 * @var integer
	 */
	public $userid = 0;
	/*
	 * EVE API Key. Passed with all requests.
	 * @var string
	 */
	public $apikey = "";
	/*
	 * EVE API Root. Use to switch to testing server root (IE to a cached demo server for testing).
	 * Default should be http://api.eve-online.com. Do not add a trailing slash.
	 */
	private $apiroot = "http://api.eve-online.com";
	/*
	 * Sets up the userid/key variables for this object. Condenses code- could also be done by setting the variables directly, 
	 * but I find having a function neater. Choose whichever works for you.
	 * @param int $userid EVE API UserID to set
	 * @param string $apikey EVE API key to set
	 */
	function setup($userid,$apikey) {
		$this->userid = $userid;
		$this->apikey = $apikey;	
	}
	/*
	 * Base request function. Queries the given target, passing authentication data as well as any args listed in $paramarray to
	 * the specified target hosted on the set API root.
	 * @param string $target API target. For example, "/account/Characters.xml.aspx". Requires prefix /.
	 * @param mixed $paramarray Parameters to pass with the request. Note that authentication is automatically sent.
	 * @return mixed|bool Returns a SimpleXML object derived from the returned XML or false if an error was generated.
	 */
	function apiRequest($target,$paramarray) {
		$ch = curl_init();
		$paramarray['userID'] = $this->userid;
		$paramarray['apiKey'] = $this->apikey;
		$t = "?";
		foreach ($paramarray as $k=>$v) {
			$t .= $k."=".$v."&";
		}
		$t = substr($t,0,-1);
		curl_setopt($ch,CURLOPT_URL,$this->apiroot.$target.$t);
		curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
		$res = curl_exec($ch);
		curl_close($ch);
		$xml = new SimpleXMLElement($res);
		if ((int) $xml->error['code'] > 0) {
			return false;
		}
		return $xml;
	}
	/*
	 * Checks to see if a character is owned by the given API key.
	 * @param string $charname Name of character (No partials or funny gubbins)
	 * @return integer|bool CharacterID if found, false if not owned.
	 */
	function isCharInAPI($charname) {
		$ret = $this->apiRequest("/account/Characters.xml.aspx",array());
		if ($ret) {
			foreach ($ret->result->rowset->row as $row) {
				if ($row['name'] == $charname) {
					return $row['characterID'];
				}
			}
			return false;
		}
	}
	/*
	 * Gets character data by name or specific ID.
	 * @param mixed $id If a string is given as input, then will return by name. If int/double/float given, gets by ID.
	 * @return object Returns SimpleXML row object. Individual variables can be accessed as $returned['varname'], eg $returned['corporationID']
	 */
	function getCharInfo($id) {
		$ret = $this->apiRequest("/account/Characters.xml.aspx",array());
		switch (gettype($id)) {
			case "string":
				$target = "name";
				break;
			default:
				$target = "characterID";
				break;
		}
		if ($ret) {
			foreach ($ret->result->rowset->row as $row) {
				if ($row[$target] == $id) {
					return $row;
				}
			}
			return false;
		}
	}
	/*
	 * Gets a single variable from the character row at /account/Characters.xml.aspx, for example corporationID or corporationName.
	 * Character may be specified by string or EVE Character ID- data type decides (string for name, anything else tries charid)
	 * @param mixed $id If a string is given as input, then will return by name. If int/double/float given, gets by ID.
	 * @param string $value Name of the field to retrieve from eg. corporationID
	 * @return mixed|bool Value of targeted variable or false if error occours
	 */
	function getCharValue($id,$value) {
	$ret = $this->apiRequest("/account/Characters.xml.aspx",array());
		switch (gettype($id)) {
			case "string":
				$target = "name";
				break;
			default:
				$target = "characterID";
				break;
		}
		if ($ret) {
			foreach ($ret->result->rowset->row as $row) {
				if ($row[$target] == $id) {
					return $row[$value];
				}
			}
			return false;
		}
	}
}
 
?>
 


EVE API Class for PHP4

Everything same as the above but changed to work with PHP4.

Example

 
$api = new apiinterface();
$api->setup("APIUSERID","APIKEY");
$ret = $api->apiRequest("account/Characters.xml.aspx"); // No array needed, will just provide basic authentication data.
echo "Corporation Name: ".$ret->children[0]->children[1]->children[0]->children[0]->attributes[2]->value;
 

The class

 
<?php
/* File: api.php
* Created on 7 Aug 2007
* EVE API PHP Class Project
* Created by James Harrison (Ix Forres)
* Edited by Dr Slurm
* @version 1.0
* @package EVEAPI
*
* Documentation and homepage at http://api.eve-metrics.com/
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
 
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
 
* You should have received a copy of the GNU General Public License
* along with this program.  If not, see <http://www.gnu.org/licenses/>.
*
* I recommend you enable the following two lines to catch errors.
* I strongly recommend you disable the ini value 'display_errors' and set error
* reporting to E_NONE for production environments to avoid data exposure.
*
* error_reporting(E_ALL);
* ini_set("display_errors","true");
*/
class apiinterface {
        /*
        * EVE API UserID. Passed with all requests.
        * @var integer
        */
        var $userid = 0;
        /*
        * EVE API Key. Passed with all requests.
        * @var string
        */
        var $apikey = "";
        /*
        * EVE API Root. Use to switch to testing server root (IE to a cached demo server for testing).
        * Default should be http://api.eve-online.com. Do not add a trailing slash.
        */
        var $apiroot = "http://api.eve-online.com";
        /*
        * Sets up the userid/key variables for this object. Condenses code- could also be done by setting the variables directly,
        * but I find having a function neater. Choose whichever works for you.
        * @param int $userid EVE API UserID to set
        * @param string $apikey EVE API key to set
        */
        function setup($userid,$apikey) {
                $this->userid = $userid;
                $this->apikey = $apikey;
        }
        /*
        * Base request function. Queries the given target, passing authentication data as well as any args listed in $paramarray to
        * the specified target hosted on the set API root.
        * @param string $target API target. For example, "/account/Characters.xml.aspx". Requires prefix /.
        * @param mixed $paramarray Parameters to pass with the request. Note that authentication is automatically sent.
        * @return mixed|bool Returns a SimpleXML object derived from the returned XML or false if an error was generated.
        */
        function apiRequest($target,$paramarray) {
                $ch = curl_init();
                $paramarray['userID'] = $this->userid;
                $paramarray['apiKey'] = $this->apikey;
                $t = "?";
                foreach ($paramarray as $k=>$v) {
                        $t .= $k."=".$v."&";
                }
                $t = substr($t,0,-1);
                curl_setopt($ch,CURLOPT_URL,$this->apiroot.$target.$t);
                curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
                $res = curl_exec($ch);
                curl_close($ch);
                return domxml_xmltree($res);
        }
        /*
        * Checks to see if a character is owned by the given API key.
        * @param string $charname Name of character (No partials or funny gubbins)
        * @return integer|bool CharacterID if found, false if not owned.
        */
        function isCharInAPI($charname) {
                $ret = $this->apiRequest("/account/Characters.xml.aspx",array());
                if ($ret) {
                			//	#document/EVEAPI////result///////rowset//////row
                        foreach ($ret->children[0]->children[1]->children[0]->children as $row) {
                                if ($row->attributes[0]->value == $charname) {
                                        return $row->attributes[1]->value;
                                }
                        }
                        return false;
                }
        }
        /*
        * Gets character data by name or specific ID.
        * @param mixed $id If a string is given as input, then will return by name. If int/double/float given, gets by ID.
        * @return object Returns SimpleXML row object. Individual variables can be accessed as $returned['varname'], eg $returned['corporationID']
        */
        function getCharInfo($id) {
                $ret = $this->apiRequest("/account/Characters.xml.aspx",array());
                switch (gettype($id)) {
                        case "string":
                        $target = "name";
                        break;
                        default:
                        $target = "characterID";
                        break;
                }
                if ($ret) {
                        foreach ($ret->children[0]->children[1]->children[0]->children as $row) {
                        	foreach($row->attributes as $attr) {
                                if ($attr->name==$target && $attr->value==$id) {
                                        return $row;
                                }
                        	}
                        }
                        return false;
                }
        }
        /*
        * Gets a single variable from the character row at /account/Characters.xml.aspx, for example corporationID or corporationName.
        * Character may be specified by string or EVE Character ID- data type decides (string for name, anything else tries charid)
        * @param mixed $id If a string is given as input, then will return by name. If int/double/float given, gets by ID.
        * @param string $value Name of the field to retrieve from eg. corporationID
        * @return mixed|bool Value of targeted variable or false if error occours
        */
        function getCharValue($id,$value) {
                $ret = $this->apiRequest("/account/Characters.xml.aspx",array());
                switch (gettype($id)) {
                        case "string":
                        $target = "name";
                        break;
                        default:
                        $target = "characterID";
                        break;
                }
                if ($ret) {
                        foreach ($ret->children[0]->children[1]->children[0]->children as $row) {
                        	if($row->attributes[0]==$id || $row->attributes[1]->value==$id) {
	                        	foreach($row->attributes as $attr){
	                        		if($attr->name==$value){
	                        			return $attr->value;
	                        		}
	                        	}
                        	}
                        }
                        return false;
                }
        }
}
 
?>
 
 
Personal tools