From 7ddd9521b3f3a397da3b0a6b56238d31414eb4be Mon Sep 17 00:00:00 2001 From: brettp Date: Thu, 28 Oct 2010 19:17:36 +0000 Subject: Standardized code in all of core, not including language files, tests, or core mods. git-svn-id: http://code.elgg.org/elgg/trunk@7124 36083f99-b078-4883-b0ff-0f9b5a30f544 --- engine/lib/api.php | 357 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 232 insertions(+), 125 deletions(-) (limited to 'engine/lib/api.php') diff --git a/engine/lib/api.php b/engine/lib/api.php index 6cb8debaa..fa7c17d80 100644 --- a/engine/lib/api.php +++ b/engine/lib/api.php @@ -1,13 +1,13 @@ 'int' | 'bool' | 'float' | 'string' | 'array' - * required => true (default) | false - * default => value (optional) - * ) - * @param string $description (optional) human readable description of the function. - * @param string $call_method (optional) Define what http method must be used for this function. Default: GET - * @param bool $require_api_auth (optional) (default is false) Does this method require API authorization? (example: API key) - * @param bool $require_user_auth (optional) (default is false) Does this method require user authorization? + * @param string $method The api name to expose - for example "myapi.dosomething" + * @param string $function Your function callback. + * @param array $parameters (optional) List of parameters in the same order as in + * your function. Default values may be set for parameters which + * allow REST api users flexibility in what parameters are passed. + * Generally, optional parameters should be after required + * parameters. + * + * This array should be in the format + * "variable" = array ( + * type => 'int' | 'bool' | 'float' | 'string' | 'array' + * required => true (default) | false + * default => value (optional) + * ) + * @param string $description (optional) human readable description of the function. + * @param string $call_method (optional) Define what http method must be used for + * this function. Default: GET + * @param bool $require_api_auth (optional) (default is false) Does this method + * require API authorization? (example: API key) + * @param bool $require_user_auth (optional) (default is false) Does this method + * require user authorization? + * * @return bool */ -function expose_function($method, $function, array $parameters = NULL, $description = "", $call_method = "GET", $require_api_auth = false, $require_user_auth = false) { +function expose_function($method, $function, array $parameters = NULL, $description = "", +$call_method = "GET", $require_api_auth = false, $require_user_auth = false) { + global $API_METHODS; if (($method == "") || ($function == "")) { - throw new InvalidParameterException(elgg_echo('InvalidParameterException:APIMethodOrFunctionNotSet')); + $msg = elgg_echo('InvalidParameterException:APIMethodOrFunctionNotSet'); + throw new InvalidParameterException($msg); } // does not check whether this method has already been exposed - good idea? @@ -72,13 +82,15 @@ function expose_function($method, $function, array $parameters = NULL, $descript if ($parameters != NULL) { if (!is_array($parameters)) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method); + throw new InvalidParameterException($msg); } // catch common mistake of not setting up param array correctly $first = current($parameters); if (!is_array($first)) { - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:APIParametersArrayStructure'), $method); + throw new InvalidParameterException($msg); } } @@ -103,7 +115,10 @@ function expose_function($method, $function, array $parameters = NULL, $descript $API_METHODS[$method]["call_method"] = 'GET'; break; default : - throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnrecognisedHttpMethod'), $call_method, $method)); + $msg = sprintf(elgg_echo('InvalidParameterException:UnrecognisedHttpMethod'), + $call_method, $method); + + throw new InvalidParameterException($msg); } $API_METHODS[$method]["require_api_auth"] = $require_api_auth; @@ -115,8 +130,12 @@ function expose_function($method, $function, array $parameters = NULL, $descript /** * Unregister an API method + * * @param string $method The api name that was exposed + * * @since 1.7.0 + * + * @return void */ function unexpose_function($method) { global $API_METHODS; @@ -128,7 +147,9 @@ function unexpose_function($method) { /** * Check that the method call has the proper API and user authentication + * * @param string $method The api name that was exposed + * * @return true or throws an exception * @throws APIException * @since 1.7.0 @@ -171,6 +192,7 @@ function authenticate_method($method) { * A method is a function which you have previously exposed using expose_function. * * @param string $method Method, e.g. "foo.bar" + * * @return GenericResult The result of the execution. * @throws APIException, CallException */ @@ -179,17 +201,24 @@ function execute_method($method) { // method must be exposed if (!isset($API_METHODS[$method])) { - throw new APIException(sprintf(elgg_echo('APIException:MethodCallNotImplemented'), $method)); + $msg = sprintf(elgg_echo('APIException:MethodCallNotImplemented'), $method); + throw new APIException($msg); } // function must be callable - if (!(isset($API_METHODS[$method]["function"])) || !(is_callable($API_METHODS[$method]["function"]))) { - throw new APIException(sprintf(elgg_echo('APIException:FunctionDoesNotExist'), $method)); + if (!(isset($API_METHODS[$method]["function"])) + || !(is_callable($API_METHODS[$method]["function"]))) { + + $msg = sprintf(elgg_echo('APIException:FunctionDoesNotExist'), $method); + throw new APIException($msg); } // check http call method if (strcmp(get_call_method(), $API_METHODS[$method]["call_method"]) != 0) { - throw new CallException(sprintf(elgg_echo('CallException:InvalidCallMethod'), $method, $API_METHODS[$method]["call_method"])); + $msg = sprintf(elgg_echo('CallException:InvalidCallMethod'), $method, + $API_METHODS[$method]["call_method"]); + + throw new CallException($msg); } $parameters = get_parameters_for_method($method); @@ -213,12 +242,14 @@ function execute_method($method) { } if ($result === false) { - throw new APIException(sprintf(elgg_echo('APIException:FunctionParseError'), $function, $serialised_parameters)); + $msg = sprintf(elgg_echo('APIException:FunctionParseError'), $function, $serialised_parameters); + throw new APIException($msg); } - if ($result === NULL) { + if ($result === NULL) { // If no value - throw new APIException(sprintf(elgg_echo('APIException:FunctionNoReturn'), $function, $serialised_parameters)); + $msg = sprintf(elgg_echo('APIException:FunctionNoReturn'), $function, $serialised_parameters); + throw new APIException($msg); } // Otherwise assume that the call was successful and return it as a success object. @@ -227,6 +258,7 @@ function execute_method($method) { /** * Get the request method. + * * @return string HTTP request method */ function get_call_method() { @@ -240,6 +272,7 @@ function get_call_method() { * an associated array. * * @param string $method The method + * * @return array containing parameters as key => value */ function get_parameters_for_method($method) { @@ -268,6 +301,7 @@ function get_parameters_for_method($method) { /** * Get POST data * Since this is called through a handler, we need to manually get the post data + * * @return POST data as string encoded as multipart/form-data */ function get_post_data() { @@ -279,7 +313,10 @@ function get_post_data() { /** * This fixes the post parameters that are munged due to page handler + * * @since 1.7.0 + * + * @return void */ function include_post_data() { @@ -307,8 +344,10 @@ function include_post_data() { /** * Verify that the required parameters are present - * @param $method - * @param $parameters + * + * @param string $method Method name + * @param array $parameters List of expected parameters + * * @return true on success or exception * @throws APIException * @since 1.7.0 @@ -325,12 +364,15 @@ function verify_parameters($method, $parameters) { foreach ($API_METHODS[$method]['parameters'] as $key => $value) { // this tests the expose structure: must be array to describe parameter and type must be defined if (!is_array($value) || !isset($value['type'])) { - throw new APIException(sprintf(elgg_echo('APIException:InvalidParameter'), $key, $method)); + + $msg = sprintf(elgg_echo('APIException:InvalidParameter'), $key, $method); + throw new APIException($msg); } // Check that the variable is present in the request if required if ($value['required'] && !array_key_exists($key, $parameters)) { - throw new APIException(sprintf(elgg_echo('APIException:MissingParameterInMethod'), $key, $method)); + $msg = sprintf(elgg_echo('APIException:MissingParameterInMethod'), $key, $method); + throw new APIException($msg); } } @@ -340,8 +382,9 @@ function verify_parameters($method, $parameters) { /** * Serialize an array of parameters for an API method call * - * @param string $method API method name - * @param array $parameters Array of parameters + * @param string $method API method name + * @param array $parameters Array of parameters + * * @return string or exception * @throws APIException * @since 1.7.0 @@ -390,7 +433,8 @@ function serialise_parameters($method, $parameters) { case 'array': // we can handle an array of strings, maybe ints, definitely not booleans or other arrays if (!is_array($parameters[$key])) { - throw new APIException(sprintf(elgg_echo('APIException:ParameterNotArray'), $key)); + $msg = sprintf(elgg_echo('APIException:ParameterNotArray'), $key); + throw new APIException($msg); } $array = "array("; @@ -402,7 +446,7 @@ function serialise_parameters($method, $parameters) { $array .= "'$k'=>'$v',"; } - $array = trim($array,","); + $array = trim($array, ","); $array .= ")"; $array = ",$array"; @@ -410,7 +454,8 @@ function serialise_parameters($method, $parameters) { $serialised_parameters .= $array; break; default: - throw new APIException(sprintf(elgg_echo('APIException:UnrecognisedTypeCast'), $value['type'], $key, $method)); + $msg = sprintf(elgg_echo('APIException:UnrecognisedTypeCast'), $value['type'], $key, $method); + throw new APIException($msg); } } @@ -421,7 +466,10 @@ function serialise_parameters($method, $parameters) { /** * PAM: Confirm that the call includes a valid API key + * * @return true if good API key - otherwise throws exception + * + * @return mixed * @throws APIException * @since 1.7.0 */ @@ -449,7 +497,9 @@ function api_auth_key() { /** * PAM: Confirm the HMAC signature + * * @return true if success - otherwise throws exception + * * @throws SecurityException * @since 1.7.0 */ @@ -463,7 +513,8 @@ function api_auth_hmac() { $api_user = get_api_user($CONFIG->site_id, $api_header->api_key); if (!$api_user) { - throw new SecurityException(elgg_echo('SecurityException:InvalidAPIKey'), ErrorResult::$RESULT_FAIL_APIKEY_INVALID); + throw new SecurityException(elgg_echo('SecurityException:InvalidAPIKey'), + ErrorResult::$RESULT_FAIL_APIKEY_INVALID); } // Get the secret key @@ -492,12 +543,15 @@ function api_auth_hmac() { } // Validate post data - if ($api_header->method=="POST") { + if ($api_header->method == "POST") { $postdata = get_post_data(); $calculated_posthash = calculate_posthash($postdata, $api_header->posthash_algo); - if (strcmp($api_header->posthash, $calculated_posthash)!=0) { - throw new SecurityException(sprintf(elgg_echo('SecurityException:InvalidPostHash'), $calculated_posthash, $api_header->posthash)); + if (strcmp($api_header->posthash, $calculated_posthash) != 0) { + $msg = sprintf(elgg_echo('SecurityException:InvalidPostHash'), + $calculated_posthash, $api_header->posthash); + + throw new SecurityException($msg); } } @@ -547,7 +601,7 @@ function get_and_validate_api_headers() { // This values determines how long the HMAC cache needs to store previous // signatures. Heavy use of HMAC is better handled with a shorter sig lifetime. // See cache_hmac_check_replay() - if (($result->time<(time()-90000)) || ($result->time>(time()+90000))) { + if (($result->time < (time() - 90000)) || ($result->time > (time() + 90000))) { throw new APIException(elgg_echo('APIException:TemporalDrift')); } @@ -581,6 +635,7 @@ function get_and_validate_api_headers() { * This also gives us an easy way to disable algorithms. * * @param string $algo The algorithm + * * @return string The php algorithm * @throws APIException if an algorithm is not supported. */ @@ -605,15 +660,20 @@ function map_api_hash($algo) { * This function signs an api request using the information provided. The signature returned * has been base64 encoded and then url encoded. * - * @param string $algo The HMAC algorithm used - * @param string $time String representation of unix time - * @param string $api_key Your api key - * @param string $secret Your private key - * @param string $get_variables URLEncoded string representation of the get variable parameters, eg "method=user&guid=2" - * @param string $post_hash Optional sha1 hash of the post data. + * @param string $algo The HMAC algorithm used + * @param string $time String representation of unix time + * @param string $nonce Nonce + * @param string $api_key Your api key + * @param string $secret_key Your private key + * @param string $get_variables URLEncoded string representation of the get variable parameters, + * eg "method=user&guid=2" + * @param string $post_hash Optional sha1 hash of the post data. + * * @return string The HMAC signature */ -function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variables, $post_hash = "") { +function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, +$get_variables, $post_hash = "") { + global $CONFIG; elgg_log("HMAC Parts: $algo, $time, $api_key, $secret_key, $get_variables, $post_hash"); @@ -624,7 +684,7 @@ function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variab hash_update($ctx, trim($nonce)); hash_update($ctx, trim($api_key)); hash_update($ctx, trim($get_variables)); - if (trim($post_hash)!="") { + if (trim($post_hash) != "") { hash_update($ctx, trim($post_hash)); } @@ -636,8 +696,9 @@ function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variab * * @todo Work out how to handle really large bits of data. * - * @param string $postdata string The post data. - * @param string $algo The algorithm used. + * @param string $postdata The post data. + * @param string $algo The algorithm used. + * * @return string The hash. */ function calculate_posthash($postdata, $algo) { @@ -653,6 +714,7 @@ function calculate_posthash($postdata, $algo) { * hasn't been seen before, and secondly it will add the given hmac to the cache. * * @param string $hmac The hmac string. + * * @return bool True if replay detected, false if not. */ function cache_hmac_check_replay($hmac) { @@ -675,6 +737,7 @@ function cache_hmac_check_replay($hmac) { * Generate a new API user for a site, returning a new keypair on success. * * @param int $site_guid The GUID of the site. (default is current site) + * * @return stdClass object or false */ function create_api_user($site_guid) { @@ -686,8 +749,8 @@ function create_api_user($site_guid) { $site_guid = (int)$site_guid; - $public = sha1(rand().$site_guid.microtime()); - $secret = sha1(rand().$site_guid.microtime().$public); + $public = sha1(rand() . $site_guid . microtime()); + $secret = sha1(rand() . $site_guid . microtime() . $public); $insert = insert_data("INSERT into {$CONFIG->dbprefix}api_users (site_guid, api_key, secret) values @@ -701,10 +764,12 @@ function create_api_user($site_guid) { } /** - * Find an API User's details based on the provided public api key. These users are not users in the traditional sense. + * Find an API User's details based on the provided public api key. + * These users are not users in the traditional sense. + * + * @param int $site_guid The GUID of the site. + * @param string $api_key The API Key * - * @param int $site_guid The GUID of the site. - * @param string $api_key The API Key * @return mixed stdClass representing the database row or false. */ function get_api_user($site_guid, $api_key) { @@ -713,14 +778,18 @@ function get_api_user($site_guid, $api_key) { $api_key = sanitise_string($api_key); $site_guid = (int)$site_guid; - return get_data_row("SELECT * from {$CONFIG->dbprefix}api_users where api_key='$api_key' and site_guid=$site_guid and active=1"); + $query = "SELECT * from {$CONFIG->dbprefix}api_users" + . " where api_key='$api_key' and site_guid=$site_guid and active=1"; + + return get_data_row($query); } /** * Revoke an api user key. * - * @param int $site_guid The GUID of the site. - * @param string $api_key The API Key (public). + * @param int $site_guid The GUID of the site. + * @param string $api_key The API Key (public). + * * @return bool */ function remove_api_user($site_guid, $api_key) { @@ -735,7 +804,7 @@ function remove_api_user($site_guid, $api_key) { } -// User Authorization functions //////////////////////////////////////////////////////////////// +// User Authorization functions /** * Check the user token @@ -743,10 +812,9 @@ function remove_api_user($site_guid, $api_key) { * it is present and is valid. The user gets logged in so with the current * session code of Elgg, that user will be logged out of all other sessions. * - * @param array/mixed $credentials * @return bool */ -function pam_auth_usertoken($credentials = NULL) { +function pam_auth_usertoken() { global $CONFIG; $token = get_input('auth_token'); @@ -765,7 +833,7 @@ function pam_auth_usertoken($credentials = NULL) { } // Not an elgg user - if ( (!$u instanceof ElggUser)) { + if ((!$u instanceof ElggUser)) { return false; } @@ -787,19 +855,21 @@ function pam_auth_usertoken($credentials = NULL) { /** * See if the user has a valid login sesson + * * @return bool */ -function pam_auth_session($credentials = NULL) { +function pam_auth_session() { return isloggedin(); } -// user token functions ///////////////////////////////////////////////////////////////////// +// user token functions /** * Obtain a token for a user. * * @param string $username The username - * @param int $expire minutes until token expires (default is 60 minutes) + * @param int $expire Minutes until token expires (default is 60 minutes) + * * @return bool */ function create_user_token($username, $expire = 60) { @@ -809,7 +879,7 @@ function create_user_token($username, $expire = 60) { $user = get_user_by_username($username); $time = time(); $time += 60 * $expire; - $token = md5(rand(). microtime() . $username . $time . $site_guid); + $token = md5(rand() . microtime() . $username . $time . $site_guid); if (!$user) { return false; @@ -817,7 +887,8 @@ function create_user_token($username, $expire = 60) { if (insert_data("INSERT into {$CONFIG->dbprefix}users_apisessions (user_guid, site_guid, token, expires) values - ({$user->guid}, $site_guid, '$token', '$time') on duplicate key update token='$token', expires='$time'")) { + ({$user->guid}, $site_guid, '$token', '$time') + on duplicate key update token='$token', expires='$time'")) { return $token; } @@ -829,6 +900,7 @@ function create_user_token($username, $expire = 60) { * * @param int $user_guid The user GUID * @param int $site_guid The ID of the site (default is current site) + * * @return false if none available or array of stdClass objects * (see users_apisessions schema for available variables in objects) * @since 1.7.0 @@ -852,11 +924,12 @@ function get_user_tokens($user_guid, $site_guid) { /** * Validate a token against a given site. * - * A token registered with one site can not be used from a different apikey(site), so be aware of this - * during development. + * A token registered with one site can not be used from a + * different apikey(site), so be aware of this during development. + * + * @param string $token The Token. + * @param int $site_guid The ID of the site (default is current site) * - * @param string $token The Token. - * @param int $site_guid The ID of the site (default is current site) * @return mixed The user id attached to the token if not expired or false. */ function validate_user_token($token, $site_guid) { @@ -884,8 +957,9 @@ function validate_user_token($token, $site_guid) { /** * Remove user token * - * @param string $token - * @param int $site_guid The ID of the site (default is current site) + * @param string $token The toekn + * @param int $site_guid The ID of the site (default is current site) + * * @return bool * @since 1.7.0 */ @@ -920,12 +994,13 @@ function remove_expired_user_tokens() { where site_guid=$site_guid and expires < $time"); } -// Client api functions /////////////////////////////////////////////////////////////////// +// Client api functions /** * Utility function to serialise a header array into its text representation. * * @param array $headers The array of headers "key" => "value" + * * @return string */ function serialise_api_headers(array $headers) { @@ -941,15 +1016,18 @@ function serialise_api_headers(array $headers) { /** * Send a raw API call to an elgg api endpoint. * - * @param array $keys The api keys. - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param string $method GET or POST - * @param string $post_data The post data + * @param array $keys The api keys. + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param string $method GET or POST + * @param string $post_data The post data * @param string $content_type The content type + * * @return string */ -function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_data = '', $content_type = 'application/octet-stream') { +function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_data = '', +$content_type = 'application/octet-stream') { + global $CONFIG; $headers = array(); @@ -972,8 +1050,8 @@ function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_da $nonce = uniqid(''); // URL encode all the parameters - foreach ($call as $k => $v){ - $encoded_params[] = urlencode($k).'='.urlencode($v); + foreach ($call as $k => $v) { + $encoded_params[] = urlencode($k) . '=' . urlencode($v); } $params = implode('&', $encoded_params); @@ -1033,9 +1111,10 @@ function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_da /** * Send a GET call * - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param array $keys The keys dependant on chosen authentication method + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param array $keys The keys dependant on chosen authentication method + * * @return string */ function send_api_get_call($url, array $call, array $keys) { @@ -1045,32 +1124,38 @@ function send_api_get_call($url, array $call, array $keys) { /** * Send a GET call * - * @param string $url URL of the endpoint. - * @param array $call Associated array of "variable" => "value" - * @param array $keys The keys dependant on chosen authentication method - * @param string $post_data The post data + * @param string $url URL of the endpoint. + * @param array $call Associated array of "variable" => "value" + * @param array $keys The keys dependant on chosen authentication method + * @param string $post_data The post data * @param string $content_type The content type + * * @return string */ -function send_api_post_call($url, array $call, array $keys, $post_data, $content_type = 'application/octet-stream') { +function send_api_post_call($url, array $call, array $keys, $post_data, +$content_type = 'application/octet-stream') { + return send_api_call($keys, $url, $call, 'POST', $post_data, $content_type); } /** - * Return a key array suitable for the API client using the standard authentication method based on api-keys and secret keys. + * Return a key array suitable for the API client using the standard + * authentication method based on api-keys and secret keys. * * @param string $secret_key Your secret key - * @param string $api_key Your api key + * @param string $api_key Your api key + * * @return array */ function get_standard_api_key_array($secret_key, $api_key) { return array('public' => $api_key, 'private' => $secret_key); } -// System functions /////////////////////////////////////////////////////////////////////// +// System functions /** * Simple api to return a list of all api's installed on the system. + * * @return array */ function list_all_apis() { @@ -1090,6 +1175,7 @@ function list_all_apis() { * * @param string $username Username * @param string $password Clear text password + * * @return string Token string or exception * @throws SecurityException */ @@ -1104,7 +1190,7 @@ function auth_gettoken($username, $password) { throw new SecurityException(elgg_echo('SecurityException:authenticationfailed')); } -// Error handler functions //////////////////////////////////////////////////////////////// +// Error handler functions /** Define a global array of errors */ $ERRORS = array(); @@ -1114,22 +1200,25 @@ $ERRORS = array(); * This function acts as a wrapper to catch and report PHP error messages. * * @see http://uk3.php.net/set-error-handler - * @param int $errno - * @param string $errmsg - * @param string $filename - * @param int $linenum - * @param array $vars - * @return none + * + * @param int $errno Error number + * @param string $errmsg Human readable message + * @param string $filename Filename + * @param int $linenum Line number + * @param array $vars Vars + * + * @return void */ -function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { +function _php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { global $ERRORS; - $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " . $filename . " (line " . $linenum . ")"; + $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file " + . $filename . " (line " . $linenum . ")"; switch ($errno) { case E_USER_ERROR: error_log("ERROR: " . $error); - $ERRORS[] = "ERROR: " .$error; + $ERRORS[] = "ERROR: " . $error; // Since this is a fatal error, we want to stop any further execution but do so gracefully. throw new Exception("ERROR: " . $error); @@ -1138,12 +1227,12 @@ function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { case E_WARNING : case E_USER_WARNING : error_log("WARNING: " . $error); - $ERRORS[] = "WARNING: " .$error; + $ERRORS[] = "WARNING: " . $error; break; default: error_log("DEBUG: " . $error); - $ERRORS[] = "DEBUG: " .$error; + $ERRORS[] = "DEBUG: " . $error; } } @@ -1153,10 +1242,11 @@ function __php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) { * uncaught exception, end API execution and return the result to the requestor * as an ErrorResult in the requested format. * - * @param Exception $exception - * @return none + * @param Exception $exception Exception + * + * @return void */ -function __php_api_exception_handler($exception) { +function _php_api_exception_handler($exception) { error_log("*** FATAL EXCEPTION (API) *** : " . $exception); @@ -1167,21 +1257,23 @@ function __php_api_exception_handler($exception) { } -// Services handler /////////////////////////////////////////// +// Services handler /** * Services handler - turns request over to the registered handler * If no handler is found, this returns a 404 error * - * @param string $handler - * @param array $request + * @param string $handler Handler name + * @param array $request Request string + * + * @return void */ function service_handler($handler, $request) { global $CONFIG; set_context('api'); - $request = explode('/',$request); + $request = explode('/', $request); // after the handler, the first identifier is response format // ex) http://example.org/services/api/rest/xml/?method=test @@ -1198,7 +1290,9 @@ function service_handler($handler, $request) { // no handlers set or bad url header("HTTP/1.0 404 Not Found"); exit; - } else if (isset($CONFIG->servicehandler[$handler]) && is_callable($CONFIG->servicehandler[$handler])) { + } else if (isset($CONFIG->servicehandler[$handler]) + && is_callable($CONFIG->servicehandler[$handler])) { + $function = $CONFIG->servicehandler[$handler]; $function($request, $handler); } else { @@ -1211,9 +1305,10 @@ function service_handler($handler, $request) { /** * Registers a web services handler * - * @param string $handler web services type + * @param string $handler Web services type * @param string $function Your function name - * @return true|false Depending on success + * + * @return bool Depending on success * @since 1.7.0 */ function register_service_handler($handler, $function) { @@ -1235,6 +1330,7 @@ function register_service_handler($handler, $function) { * with register_service_handler(). * * @param string $handler web services type + * * @return 1.7.0 */ function unregister_service_handler($handler) { @@ -1244,10 +1340,12 @@ function unregister_service_handler($handler) { } } -// REST handler ////////////////////////////////////////////////////////////// +// REST handler /** * REST API handler + * + * @return void */ function rest_handler() { global $CONFIG; @@ -1255,10 +1353,17 @@ function rest_handler() { require $CONFIG->path . "services/api/rest_api.php"; } -// Initialisation ///////////////////////////////////////////////////////////// +// Initialisation /** * Unit tests for API + * + * @param sting $hook unit_test + * @param string $type system + * @param mixed $value Array of tests + * @param mixed $params Params + * + * @return array */ function api_unit_test($hook, $type, $value, $params) { global $CONFIG; @@ -1269,15 +1374,17 @@ function api_unit_test($hook, $type, $value, $params) { /** * Initialise the API subsystem. * + * @return void */ function api_init() { // Register a page handler, so we can have nice URLs - register_service_handler('rest','rest_handler'); + register_service_handler('rest', 'rest_handler'); register_plugin_hook('unit_test', 'system', 'api_unit_test'); // expose the list of api methods - expose_function("system.api.list", "list_all_apis", NULL, elgg_echo("system.api.list"), "GET", false, false); + expose_function("system.api.list", "list_all_apis", NULL, + elgg_echo("system.api.list"), "GET", false, false); // The authentication token api expose_function("auth.gettoken", @@ -1292,4 +1399,4 @@ function api_init() { } -register_elgg_event_handler('init','system','api_init'); +register_elgg_event_handler('init', 'system', 'api_init'); -- cgit v1.2.3