API Class

Files

/engine/class.www-api.php

Introduction

API class is one of the core classes of Wave Framework. Every command and function in Wave Framework is executed through API object. API class implements State Class - which stores configuration - and executes any and all functionality that is built within Wave Framework. It is not recommended to modify this class, in fact this class is defined as final. Methods of this class take user input, load MVC objects and execute their methods and return data in the appropriate format.

API class executes methods of both public API calls and private authenticated API profiles.

API takes any type of input data as an array, but considers input data that has 'www-' prefix (called the 'wave prefix') as Wave Framework specific and this can carry additional functionality. More details about Wave Framework API related calls is detailed in API feature guide.

Using API Class

API class is an internal Wave Framework class and should not be used outside the context of Wave Framework. API and Data Handlers use the API in the following way, for example:

	
	// It is recommended to also define a state
	require('/engine/class.www-state.php');
	$state=new WWW_State();
	
	// Including and loading an API object
	require('/engine/class.www-api.php');
	$api=new WWW_API($state);
	

Then to execute an API call, you simply have to call the command() method with input data, like this:

	
	// An example input array
	$input=array('www-command'=>'example-get');
	
	// Executing the command
	$result=$api->command($input);
			
	// Printing out the result
	print_r($result);
	

You can take a look at the API Handler code to see how additional data is configured about API class.

API Class Parameters

private $commandBuffer=array()

This variable is used to store results of API call. It acts as a buffer for API, which will be checked when another API call is made with the exact same input data.

private $apiProfiles=array()

This holds data about API profiles from '/resources/api.profiles.ini', content of which will be checked by API whenever API call is made that is not public.

private $apiObservers=array()

This variable holds data about API observers from /resources/api.observers.ini file. If an API call is made, then this variable content will be checked to execute additional API calls, if defined.

public $apiLoggerData=array()

This is an array that stores data that will be logged by Logger object, if Logger is used in the system. Content length and other data is stored for logging purposes in this array.

private $splitTimes=array()

This variable stores performance related timestamps, if splitTime() method is called by the API.

public $state=false

This variable stores the initialized State object that carries a lot of configuration and environment data and functionality.

public $apc=false

This variable defines whether APC is available in the server environment. If this variable is true, then some caching methods will utilize APC instead of Filesystem.

public $memcache=false

This variable defines whether Memcache is available in the server environment. If this variable is true, then some caching methods will utilize Memcache instead of Filesystem.

public $databaseCache=false

This variable holds database cache, since this connection can be different from the main Database connection used by the system, while still using the same class for the requests.

public $callIndex=0

This is a counter that stores the depth of API calls. Since API calls can execute other API calls, this variable is used to determine some caching and buffer related data when specific API call is references by API class.

public $cacheIndex

This is an index of cache files that have been referenced within the system. This is used so that certain calls do not have to be repeated, if the same cache is referred multiple times within a single request.

public $noCache=array()

This variable holds data about API execution call-index values and whether this specific API call can be cached or not. This is for internal maintenance when dealing with which API call to cache and which not.

public $returnTypes=array()

This holds the return type information of API calls. This can be later fetched by controllers to see what type of data is being requested from the API.

public $requestedVersion=false

This method stores version number for Models, Views and Controller files loaded through the API. These files have to be set in the subfolders of /model/, /view/ and /controller folders. If files are not found, then the most recent version is used. If this is set to false, then core files are used instead.

private $internalLogging=false

This holds configuration value from State and turns on internal logging, if configuration has internal logging enabled. If this remains false, then internal log entries will not be stored.

private $internalLog=array()

This is an array that stores all the internal log entries that will be written to Filesystem once API class has finished dealing with the request.

private $closeProcess=false

This is used only by resultFile() method to close API processing once file download happens.

API Class Methods

final public function __construct($state=false,$apiProfiles=false)

API object construction accepts State object in $state and array data of API profiles as $apiProfiles. If State is not defined, then API class attempts to automatically create a new State object, thus API class is highly dependent on State Class being present. API object construction also loads Factory class, if it is not defined and tests if server supports APC or not. If API profiles are not submitted to API during construction, then API will attempt to load API profiles from the *.ini file. Same applies to observers.

final public function __destruct()

Once API object is not used anymore, the object attempts to write internal log to Filesystem if internal log is used and has any log data to store. It also closes Memcache connection if such is used.

final public function command($apiInputData=array(),$useBuffer=false,$apiValidation=true,$useLogger=false)

This is one of the two core methods of API class. It accepts input data from $apiInputData which is an array of keys and values. Some keys are API dependent flags with the wave prefix of 'www-'. $useBuffer setting defines if buffer can be used, which means that if the same exact input has already been sent within the same HTTP request, then it returns data from buffer rather than going through the process again. $apiValidation is a flag that sets whether API profiles are validated or not, this setting is turned off for internal API calls that have already been validated. $useLogger is a flag that tells API that Logger class is used by the system. This method validates the API call, loads MVC objects and executes their methods and sends the result to output() function.

This is the step by step list of what command() method does:

final private function output($apiResult,$apiState,$useLogger=true)

This is one of the two core methods of API class. Method is private and is only called within the class. This method is used to parse the data returned from API and returned to the user agent or system based on requested format. $apiResult is an array that has been returned from command() method, $apiState and $useLogger are also defined when the method is called. It returns the data as a PHP array, XML string, INI string or any other format and with or without HTTP response headers.

This is the step by step list of what output() method does:

final private function apiCallbacks($data,$useLogger,$returnType)

It is possible to execute certain callbacks with the API based on what data is returned from API. It is possible to set headers with this method that will be sent to returned output buffer. It is also possible to set and unset cookies and sessions. It is also possible to redirect the user agent with a callback. $data is the return data from the API and $logger and $returnType are defined from output() method that makes the call to apiCallbacks(). This method is private and cannot be used outside the class.

This is the step by step list of what apiCallbacks() method does:

final public function resultStream($stream)

This method can be called from controllers to either return a string or print our a string to the browser. This is technically a shorthand to returning 'www-data' array key with a string value. This can be used to build various custom output formats that are not handled by Wave Framework API itself.

final public function resultFile($location,$name=false,$contentType=false)

This method can be called from controllers to either return contents of a file or force a file download in the requesting browser when making HTTP API request.

final private function toXML($apiResult,$type=false)

This is a method that converts an array to an XML string. It can convert to both common XML as well as to RSS format. $apiResult is the data sent to the request. If $type is set to 'rss' then RSS formatting is used, otherwise a regular XML is returned. This is an internal method used by output() call.

final private function toXMLnode($data,$numeric='node')

This is a helper method for toXML() method and is used to build an XML node. This method is private and is not used elsewhere. $numeric is what is the tag name for keys that are numeric (such as numeric array keys).

final private function toCSV($apiResult)

This method converts an array to CSV format, based on the structure of the array. It uses tabs as a column separator and separates values by commas, if sub-arrays are used. $apiResult is the data sent by output() method.

final private function toINI($apiResult)

This attempts to convert the data array of $apiResult to INI format. It handles also subarrays and other possible conditions in the array.

final public function encryptData($data,$key,$secretKey=false)

This method uses API class internal encryption function to encrypt $data string with a key and a secret key (if set). If only $key is set, then ECB mode is used for Rijndael encryption.

final public function decryptData($data,$key,$secretKey=false)

This will decrypt Rijndael encoded data string, set with $data. $key and $secretKey should be the same that they were when the data was encrypted.

final public function unsetTaggedCache($tags)

This method unsets all cache that has been stored with a specific tag keyword. $tags variable can both be a string or an array of keywords. Every cache related to those keywords will be removed.

final public function clearBuffer()

This method is used to clear current API command buffer. This is an optimization method and should be used only of a lot of API calls are made that might fill the memory allocated to PHP. What this method does is that it tells API object to empty the internal variable that stores the results of all API calls that have already been sent to API.

final public function getExistingCache($key)

This method returns currently existing cache for currently executed API call, if it exists. This allows you to always load cache from system in case a new response cannot be generated. It returns cache with the key $key.

final public function getExistingCacheTime($key)

If cache exists for currently executed API call, then this method returns the UNIX timestamp of the time when that cache was written. It returns cache timestamp with the key $key.

final public function setCache($keyAddress,$value,$tags=false,$custom=false)

This method can be used to store cache for whatever needs by storing $key and giving it a value of $value. Cache tagging can also be used with custom tag by sending a keyword with $tags or an array of keywords.

final public function getCache($keyAddress,$limit=false,$custom=false)

This method fetches data from cache based on cache keyword $key, if cache exists. This should be the same keyword that was used in setCache() method, when storing cache. $limit sets the timestamp after which cache won't be accepted anymore and $custom sets if the cache has been called by MVC Objects or not.

final public function cacheTime($keyAddress,$custom=false)

This function returns the timestamp of when the cache of keyword $key, was created, if such a cache exists.

final public function unsetCache($keyAddress,$custom=false)

This method removes cache that was stored with the keyword $key, if such a cache exists.

final public function logEntry($key,$data=false)

This method attempts to write an entry to internal log. Log entry is stored with a $key and entry itself should be the $data. $key is needed to easily find the log entry later on.

final public function splitTime($key='api')

This method is a timer that can be used to grade performance within the system. When this method is called with some $key first, it will start the timer and write an entry to log about it. If the same $key is called again, then a log entry is created with the amount of microseconds that have passed since the last time this method was called with this $key.

final private function ksortArray($data)

This helper method is used to sort an array (and sub-arrays) based on keys. It essentially applies ksort() method recursively to an array.

final public function filter($string,$type,$exceptions=false)

This method simply filters a string and returns the filtered string. Various exception characters can be set in $exceptions string and these will not be filtered. You can set the type to 'integer', 'float', 'numeric', 'alpha' or 'alphanumeric'.