Teknik is a suite of services with attractive and functional interfaces. https://www.teknik.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

DocumentationGenerator.php 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244
  1. <?php
  2. /**
  3. * Piwik - free/libre analytics platform
  4. *
  5. * @link http://piwik.org
  6. * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  7. *
  8. */
  9. namespace Piwik\API;
  10. use Exception;
  11. use Piwik\Common;
  12. use Piwik\Piwik;
  13. use Piwik\Url;
  14. class DocumentationGenerator
  15. {
  16. protected $modulesToHide = array('CoreAdminHome', 'DBStats');
  17. protected $countPluginsLoaded = 0;
  18. /**
  19. * trigger loading all plugins with an API.php file in the Proxy
  20. */
  21. public function __construct()
  22. {
  23. $plugins = \Piwik\Plugin\Manager::getInstance()->getLoadedPluginsName();
  24. foreach ($plugins as $plugin) {
  25. try {
  26. $className = Request::getClassNameAPI($plugin);
  27. Proxy::getInstance()->registerClass($className);
  28. } catch (Exception $e) {
  29. }
  30. }
  31. }
  32. /**
  33. * Returns a HTML page containing help for all the successfully loaded APIs.
  34. * For each module it will return a mini help with the method names, parameters to give,
  35. * links to get the result in Xml/Csv/etc
  36. *
  37. * @param bool $outputExampleUrls
  38. * @param string $prefixUrls
  39. * @return string
  40. */
  41. public function getAllInterfaceString($outputExampleUrls = true, $prefixUrls = '')
  42. {
  43. if (!empty($prefixUrls)) {
  44. $prefixUrls = 'http://demo.piwik.org/';
  45. }
  46. $str = $toc = '';
  47. $token_auth = "&token_auth=" . Piwik::getCurrentUserTokenAuth();
  48. $parametersToSet = array(
  49. 'idSite' => Common::getRequestVar('idSite', 1, 'int'),
  50. 'period' => Common::getRequestVar('period', 'day', 'string'),
  51. 'date' => Common::getRequestVar('date', 'today', 'string')
  52. );
  53. foreach (Proxy::getInstance()->getMetadata() as $class => $info) {
  54. $moduleName = Proxy::getInstance()->getModuleNameFromClassName($class);
  55. if (in_array($moduleName, $this->modulesToHide)) {
  56. continue;
  57. }
  58. $toc .= "<a href='#$moduleName'>$moduleName</a><br/>";
  59. $str .= "\n<a name='$moduleName' id='$moduleName'></a><h2>Module " . $moduleName . "</h2>";
  60. $str .= "<div class='apiDescription'> " . $info['__documentation'] . " </div>";
  61. foreach ($info as $methodName => $infoMethod) {
  62. if ($methodName == '__documentation') {
  63. continue;
  64. }
  65. $params = $this->getParametersString($class, $methodName);
  66. $str .= "\n <div class='apiMethod'>- <b>$moduleName.$methodName </b>" . $params . "";
  67. $str .= '<small>';
  68. if ($outputExampleUrls) {
  69. // we prefix all URLs with $prefixUrls
  70. // used when we include this output in the Piwik official documentation for example
  71. $str .= "<span class=\"example\">";
  72. $exampleUrl = $this->getExampleUrl($class, $methodName, $parametersToSet);
  73. if ($exampleUrl !== false) {
  74. $lastNUrls = '';
  75. if (preg_match('/(&period)|(&date)/', $exampleUrl)) {
  76. $exampleUrlRss = $prefixUrls . $this->getExampleUrl($class, $methodName, array('date' => 'last10', 'period' => 'day') + $parametersToSet);
  77. $lastNUrls = ", RSS of the last <a target=_blank href='$exampleUrlRss&format=rss$token_auth&translateColumnNames=1'>10 days</a>";
  78. }
  79. $exampleUrl = $prefixUrls . $exampleUrl;
  80. $str .= " [ Example in
  81. <a target=_blank href='$exampleUrl&format=xml$token_auth'>XML</a>,
  82. <a target=_blank href='$exampleUrl&format=JSON$token_auth'>Json</a>,
  83. <a target=_blank href='$exampleUrl&format=Tsv$token_auth&translateColumnNames=1'>Tsv (Excel)</a>
  84. $lastNUrls
  85. ]";
  86. } else {
  87. $str .= " [ No example available ]";
  88. }
  89. $str .= "</span>";
  90. }
  91. $str .= '</small>';
  92. $str .= "</div>\n";
  93. }
  94. $str .= '<div style="margin:15px;"><a href="#topApiRef">↑ Back to top</a></div>';
  95. }
  96. $str = "<h2 id='topApiRef' name='topApiRef'>Quick access to APIs</h2>
  97. $toc
  98. $str";
  99. return $str;
  100. }
  101. /**
  102. * Returns a string containing links to examples on how to call a given method on a given API
  103. * It will export links to XML, CSV, HTML, JSON, PHP, etc.
  104. * It will not export links for methods such as deleteSite or deleteUser
  105. *
  106. * @param string $class the class
  107. * @param string $methodName the method
  108. * @param array $parametersToSet parameters to set
  109. * @return string|bool when not possible
  110. */
  111. public function getExampleUrl($class, $methodName, $parametersToSet = array())
  112. {
  113. $knowExampleDefaultParametersValues = array(
  114. 'access' => 'view',
  115. 'userLogin' => 'test',
  116. 'passwordMd5ied' => 'passwordExample',
  117. 'email' => 'test@example.org',
  118. 'languageCode' => 'fr',
  119. 'url' => 'http://forum.piwik.org/',
  120. 'pageUrl' => 'http://forum.piwik.org/',
  121. 'apiModule' => 'UserCountry',
  122. 'apiAction' => 'getCountry',
  123. 'lastMinutes' => '30',
  124. 'abandonedCarts' => '0',
  125. 'segmentName' => 'pageTitle',
  126. 'ip' => '194.57.91.215',
  127. 'idSites' => '1,2',
  128. 'idAlert' => '1',
  129. 'seconds' => '3600',
  130. // 'segmentName' => 'browserCode',
  131. );
  132. foreach ($parametersToSet as $name => $value) {
  133. $knowExampleDefaultParametersValues[$name] = $value;
  134. }
  135. // no links for these method names
  136. $doNotPrintExampleForTheseMethods = array(
  137. //Sites
  138. 'deleteSite',
  139. 'addSite',
  140. 'updateSite',
  141. 'addSiteAliasUrls',
  142. //Users
  143. 'deleteUser',
  144. 'addUser',
  145. 'updateUser',
  146. 'setUserAccess',
  147. //Goals
  148. 'addGoal',
  149. 'updateGoal',
  150. 'deleteGoal',
  151. );
  152. if (in_array($methodName, $doNotPrintExampleForTheseMethods)) {
  153. return false;
  154. }
  155. // we try to give an URL example to call the API
  156. $aParameters = Proxy::getInstance()->getParametersList($class, $methodName);
  157. // Kindly force some known generic parameters to appear in the final list
  158. // the parameter 'format' can be set to all API methods (used in tests)
  159. // the parameter 'hideIdSubDatable' is used for integration tests only
  160. // the parameter 'serialize' sets php outputs human readable, used in integration tests and debug
  161. // the parameter 'language' sets the language for the response (eg. country names)
  162. // the parameter 'flat' reduces a hierarchical table to a single level by concatenating labels
  163. // the parameter 'include_aggregate_rows' can be set to include inner nodes in flat reports
  164. // the parameter 'translateColumnNames' can be set to translate metric names in csv/tsv exports
  165. $aParameters['format'] = false;
  166. $aParameters['hideIdSubDatable'] = false;
  167. $aParameters['serialize'] = false;
  168. $aParameters['language'] = false;
  169. $aParameters['translateColumnNames'] = false;
  170. $aParameters['label'] = false;
  171. $aParameters['flat'] = false;
  172. $aParameters['include_aggregate_rows'] = false;
  173. $aParameters['filter_limit'] = false; //@review without adding this, I can not set filter_limit in $otherRequestParameters integration tests
  174. $aParameters['filter_sort_column'] = false; //@review without adding this, I can not set filter_sort_column in $otherRequestParameters integration tests
  175. $aParameters['filter_sort_order'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters integration tests
  176. $aParameters['filter_truncate'] = false;
  177. $aParameters['hideColumns'] = false;
  178. $aParameters['showColumns'] = false;
  179. $aParameters['filter_pattern_recursive'] = false;
  180. $aParameters['pivotBy'] = false;
  181. $aParameters['pivotByColumn'] = false;
  182. $aParameters['pivotByColumnLimit'] = false;
  183. $aParameters['disable_queued_filters'] = false;
  184. $aParameters['disable_generic_filters'] = false;
  185. $moduleName = Proxy::getInstance()->getModuleNameFromClassName($class);
  186. $aParameters = array_merge(array('module' => 'API', 'method' => $moduleName . '.' . $methodName), $aParameters);
  187. foreach ($aParameters as $nameVariable => &$defaultValue) {
  188. if (isset($knowExampleDefaultParametersValues[$nameVariable])) {
  189. $defaultValue = $knowExampleDefaultParametersValues[$nameVariable];
  190. } // if there isn't a default value for a given parameter,
  191. // we need a 'know default value' or we can't generate the link
  192. elseif ($defaultValue instanceof NoDefaultValue) {
  193. return false;
  194. }
  195. }
  196. return '?' . Url::getQueryStringFromParameters($aParameters);
  197. }
  198. /**
  199. * Returns the methods $class.$name parameters (and default value if provided) as a string.
  200. *
  201. * @param string $class The class name
  202. * @param string $name The method name
  203. * @return string For example "(idSite, period, date = 'today')"
  204. */
  205. public function getParametersString($class, $name)
  206. {
  207. $aParameters = Proxy::getInstance()->getParametersList($class, $name);
  208. $asParameters = array();
  209. foreach ($aParameters as $nameVariable => $defaultValue) {
  210. // Do not show API parameters starting with _
  211. // They are supposed to be used only in internal API calls
  212. if (strpos($nameVariable, '_') === 0) {
  213. continue;
  214. }
  215. $str = $nameVariable;
  216. if (!($defaultValue instanceof NoDefaultValue)) {
  217. if (is_array($defaultValue)) {
  218. $str .= " = 'Array'";
  219. } else {
  220. $str .= " = '$defaultValue'";
  221. }
  222. }
  223. $asParameters[] = $str;
  224. }
  225. $sParameters = implode(", ", $asParameters);
  226. return "($sParameters)";
  227. }
  228. }