diff options
Diffstat (limited to 'modules/API/Proxy.php')
| -rwxr-xr-x | modules/API/Proxy.php | 342 |
1 files changed, 171 insertions, 171 deletions
diff --git a/modules/API/Proxy.php b/modules/API/Proxy.php index b8eff71d35..04a43fc4c4 100755 --- a/modules/API/Proxy.php +++ b/modules/API/Proxy.php @@ -1,24 +1,24 @@ -<?php
-/**
- * Piwik - Open source web analytics
- *
- * @link http://piwik.org
- * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
- * @version $Id$
- *
- * @package Piwik_API
- */
-
+<?php +/** + * Piwik - Open source web analytics + * + * @link http://piwik.org + * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later + * @version $Id$ + * + * @package Piwik_API + */ + /** * The API Proxy receives all the API calls requests and forwards them to the given module. * * It registers all the APIable modules (@see Piwik_Apiable) * The class checks that a call to the API has the correct number of parameters. - * The proxy is a singleton that has the knowledge of every method available, their parameters and default values.
+ * The proxy is a singleton that has the knowledge of every method available, their parameters and default values. * * It can also log the performances of the API calls (time spent, parameter values, etc.) - *
+ * * @package Piwik_API */ class Piwik_API_Proxy @@ -29,18 +29,18 @@ class Piwik_API_Proxy protected $alreadyRegistered = array(); private $api = array(); -
+ // when a parameter doesn't have a default value we use this constant const NO_DEFAULT_VALUE = null; static private $instance = null; protected function __construct() {} -
- /**
- * Singleton, returns instance
- *
- * @return Piwik_API_Proxy
+ + /** + * Singleton, returns instance + * + * @return Piwik_API_Proxy */ static public function getInstance() { @@ -61,8 +61,8 @@ class Piwik_API_Proxy * - the API file must be located in plugins/ModuleName/API.php * for example plugins/Referers/API.php * - * The method will introspect the methods, their parameters, etc.
- *
+ * The method will introspect the methods, their parameters, etc. + * * @param string ModuleName eg. "UserSettings" */ public function registerClass( $fileName ) @@ -141,120 +141,120 @@ class Piwik_API_Proxy } $this->alreadyRegistered[$fileName] = true; - }
-
- /**
- * Returns the 'moduleName' part of 'Piwik_moduleName_API' classname
- *
- * @param string moduleName
- * @return string className
- */
- protected function getModuleNameFromClassName( $className )
- {
- $start = strpos($className, '_') + 1;
- return substr($className, $start , strrpos($className, '_') - $start);
- }
-
- /**
- * Returns a string containing links to examples on how to call a given method on a given API
- * It will export links to XML, CSV, HTML, JSON, PHP, etc.
- * It will not export links for methods such as deleteSite or deleteUser
- *
- * @param string the class
- * @param methodName the method
- * @return string|false when not possible
- */
- public function getExampleUrl($class, $methodName, $parametersToSet = array())
- {
- $knowExampleDefaultParametersValues = array(
- 'access' => 'view',
- 'idSite' => '1',
- 'userLogin' => 'test',
+ } + + /** + * Returns the 'moduleName' part of 'Piwik_moduleName_API' classname + * + * @param string moduleName + * @return string className + */ + protected function getModuleNameFromClassName( $className ) + { + $start = strpos($className, '_') + 1; + return substr($className, $start , strrpos($className, '_') - $start); + } + + /** + * Returns a string containing links to examples on how to call a given method on a given API + * It will export links to XML, CSV, HTML, JSON, PHP, etc. + * It will not export links for methods such as deleteSite or deleteUser + * + * @param string the class + * @param methodName the method + * @return string|false when not possible + */ + public function getExampleUrl($class, $methodName, $parametersToSet = array()) + { + $knowExampleDefaultParametersValues = array( + 'access' => 'view', + 'idSite' => '1', + 'userLogin' => 'test', 'password' => 'passwordExample', - 'passwordMd5ied' => 'passwordExample',
- 'email' => 'test@example.org',
-
- 'siteName' => 'new example website',
- 'urls' => 'http://example.org', // used in addSite, updateSite
-
- 'period' => 'day',
- 'date' => 'today',
+ 'passwordMd5ied' => 'passwordExample', + 'email' => 'test@example.org', + + 'siteName' => 'new example website', + 'urls' => 'http://example.org', // used in addSite, updateSite + + 'period' => 'day', + 'date' => 'today', ); foreach($parametersToSet as $name => $value) { $knowExampleDefaultParametersValues[$name] = $value; - }
-
- // no links for these method names
- $doNotPrintExampleForTheseMethods = array(
- 'deleteSite',
- 'deleteUser',
- );
-
- if(in_array($methodName,$doNotPrintExampleForTheseMethods))
- {
- return false;
- }
-
-
- // we try to give an URL example to call the API
- $aParameters = $this->getParametersList($class, $methodName);
- $moduleName = $this->getModuleNameFromClassName($class);
- $urlExample = '?module=API&method='.$moduleName.'.'.$methodName.'&';
- foreach($aParameters as $nameVariable=> $defaultValue)
- {
- // if there isn't a default value for a given parameter,
- // we need a 'know default value' or we can't generate the link
- if($defaultValue === Piwik_API_Proxy::NO_DEFAULT_VALUE)
- {
- if(isset($knowExampleDefaultParametersValues[$nameVariable]))
- {
- $exampleValue = $knowExampleDefaultParametersValues[$nameVariable];
- $urlExample .= $nameVariable . '=' . $exampleValue . '&';
- }
- else
- {
- return false;
- }
- }
-
- }
-
- return substr($urlExample,0,-1);
- }
-
- /**
- * Returns a HTML page containing help for all the successfully loaded APIs.
- *
- * For each module it will return a mini help with the method names, parameters to give,
- * links to get the result in Xml/Csv/etc
- *
- * @return string
+ } + + // no links for these method names + $doNotPrintExampleForTheseMethods = array( + 'deleteSite', + 'deleteUser', + ); + + if(in_array($methodName,$doNotPrintExampleForTheseMethods)) + { + return false; + } + + + // we try to give an URL example to call the API + $aParameters = $this->getParametersList($class, $methodName); + $moduleName = $this->getModuleNameFromClassName($class); + $urlExample = '?module=API&method='.$moduleName.'.'.$methodName.'&'; + foreach($aParameters as $nameVariable=> $defaultValue) + { + // if there isn't a default value for a given parameter, + // we need a 'know default value' or we can't generate the link + if($defaultValue === Piwik_API_Proxy::NO_DEFAULT_VALUE) + { + if(isset($knowExampleDefaultParametersValues[$nameVariable])) + { + $exampleValue = $knowExampleDefaultParametersValues[$nameVariable]; + $urlExample .= $nameVariable . '=' . $exampleValue . '&'; + } + else + { + return false; + } + } + + } + + return substr($urlExample,0,-1); + } + + /** + * Returns a HTML page containing help for all the successfully loaded APIs. + * + * For each module it will return a mini help with the method names, parameters to give, + * links to get the result in Xml/Csv/etc + * + * @return string */ public function getAllInterfaceString( $outputExampleUrls = true, $prefixUrls = '' ) { $str = ''; foreach($this->api as $class => $info) - {
+ { $moduleName = $this->getModuleNameFromClassName($class); $str .= "\n<h3>Module ".$moduleName."</h3>"; foreach($info as $methodName => $infoMethod) - {
-
+ { + $params = $this->getStrListParameters($class, $methodName); - $str .= "\n" . "- <b>$moduleName.$methodName " . $params . "</b>";
-
- $str .= '<small>';
-
- if($outputExampleUrls)
+ $str .= "\n" . "- <b>$moduleName.$methodName " . $params . "</b>"; + + $str .= '<small>'; + + if($outputExampleUrls) { // we prefix all URLs with $prefixUrls - // used when we include this output in the Piwik official documentation for example
- $exampleUrl = $this->getExampleUrl($class, $methodName);
- if($exampleUrl !== false)
+ // used when we include this output in the Piwik official documentation for example + $exampleUrl = $this->getExampleUrl($class, $methodName); + if($exampleUrl !== false) { $lastNUrls = ''; if( ereg('(&period)|(&date)',$exampleUrl)) @@ -263,23 +263,23 @@ class Piwik_API_Proxy $exampleUrlRss2 = $prefixUrls . $this->getExampleUrl($class, $methodName, array('date' => 'last5','period' => 'week',)); $lastNUrls = ", RSS of the last <a target=_blank href='$exampleUrlRss1&format=rss'>10 days</a>, <a target=_blank href='$exampleUrlRss2&format=Rss'>5 weeks</a>, XML of the <a target=_blank href='$exampleUrlRss1&format=xml'>last 10 days</a>"; - }
- $exampleUrl = $prefixUrls . $exampleUrl ;
- $str .= " [ Example in
- <a target=_blank href='$exampleUrl&format=xml'>XML</a>,
- <a target=_blank href='$exampleUrl&format=PHP&prettyDisplay=true'>PHP</a>,
- <a target=_blank href='$exampleUrl&format=JSON'>Json</a>,
+ } + $exampleUrl = $prefixUrls . $exampleUrl ; + $str .= " [ Example in + <a target=_blank href='$exampleUrl&format=xml'>XML</a>, + <a target=_blank href='$exampleUrl&format=PHP&prettyDisplay=true'>PHP</a>, + <a target=_blank href='$exampleUrl&format=JSON'>Json</a>, <a target=_blank href='$exampleUrl&format=Csv'>Csv</a>, <a target=_blank href='$exampleUrl&format=Html'>Basic html</a> - $lastNUrls
- ]";
- }
- else
- {
- $str .= " [ No example available ]";
- }
- }
- $str .= '</small>';
+ $lastNUrls + ]"; + } + else + { + $str .= " [ No example available ]"; + } + } + $str .= '</small>'; $str .= "\n<br>"; } } @@ -289,8 +289,8 @@ class Piwik_API_Proxy /** * Returns the methods $class.$name parameters (and default value if provided) as a string. * - * @param string The class name
- * @param string The method name
+ * @param string The class name + * @param string The method name * @return string For example "(idSite, period, date = 'today')" */ private function getStrListParameters($class, $name) @@ -313,8 +313,8 @@ class Piwik_API_Proxy /** * Returns the parameters names and default values for the method $name * of the class $class - *
- * @param string The class name
+ * + * @param string The class name * @param string The method name * @return array Format array( * 'testParameter' => null, // no default value @@ -328,10 +328,10 @@ class Piwik_API_Proxy } /** - * Returns the number of required parameters (parameters without default values).
- *
- * @param string The class name
- * @param string The method name
+ * Returns the number of required parameters (parameters without default values). + * + * @param string The class name + * @param string The method name * @return int The number of required parameters */ private function getNumberOfRequiredParameters($class, $name) @@ -340,10 +340,10 @@ class Piwik_API_Proxy } /** - * Returns true if the method is found in the API of the given class name.
- *
- * @param string The class name
- * @param string The method name
+ * Returns true if the method is found in the API of the given class name. + * + * @param string The class name + * @param string The method name * @return bool */ private function isMethodAvailable( $className, $methodName) @@ -353,11 +353,11 @@ class Piwik_API_Proxy /** - * Checks that the count of the given parameters do match with the count of the required ones
- *
- * @param string The class name
- * @param string The method name
- * @param array
+ * Checks that the count of the given parameters do match with the count of the required ones + * + * @param string The class name + * @param string The method name + * @param array * @throws exception If less parameters than required were given */ private function checkNumberOfParametersMatch($className, $methodName, $parameters) @@ -374,7 +374,7 @@ class Piwik_API_Proxy /** * Checks that the class is a Singleton (presence of the getInstance() method) - *
+ * * @param string The class name * @throws exception If the class is not a Singleton */ @@ -388,8 +388,8 @@ class Piwik_API_Proxy /** * Checks that the method exists in the class - *
- * @param string The class name
+ * + * @param string The class name * @param string The method name * @throws exception If the method is not found */ @@ -406,9 +406,9 @@ class Piwik_API_Proxy * * For exemple for $module = 'Referers' it returns 'Piwik_Referers_API' * Piwik_Referers_API is the class that extends Piwik_Apiable - * and that contains the methods to be published in the API.
- *
- * @param string module name
+ * and that contains the methods to be published in the API. + * + * @param string module name * @return string class name */ protected function getClassNameFromModule($module) @@ -416,27 +416,27 @@ class Piwik_API_Proxy $class = Piwik::prefixClass($module ."_API"); return $class; } -
- /**
- * Magic method used to set a flag telling the module named currently being called
- *
- */
- public function __get($name)
- {
- self::$classCalled = $name;
- return $this;
+ + /** + * Magic method used to set a flag telling the module named currently being called + * + */ + public function __get($name) + { + self::$classCalled = $name; + return $this; } -
+ /** * Method always called when making an API request. * It checks several things before actually calling the real method on the given module. - *
- * It also logs the API calls, with the parameters values, the returned value, the performance, etc.
- * You can enable logging in config/global.ini.php (log_api_call)
- *
- * @param string The method name
- * @param array The parameters
- *
+ * + * It also logs the API calls, with the parameters values, the returned value, the performance, etc. + * You can enable logging in config/global.ini.php (log_api_call) + * + * @param string The method name + * @param array The parameters + * * @throws Piwik_Access_NoAccessException */ public function __call($methodName, $parameterValues ) |