Skip to content

Commit

Permalink
Slightly better code
Browse files Browse the repository at this point in the history
  • Loading branch information
@mattab
mattab committed Dec 18, 2016
1 parent 245d08b commit dae9b48
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 129 deletions.
195 changes: 68 additions & 127 deletions core/API/DocumentationGenerator.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,73 +43,41 @@ public function __construct()

/**
* 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
*
* @param bool $outputExampleUrls
* @param string $prefixUrls
* @param bool $displayTitlesAsAngularDirective Set to false for the API ref doc at http://developer.piwik.org/api-reference/reporting-api where we need to display titles without using AngularJS
* @return string
*/
public function getAllInterfaceString($outputExampleUrls = true, $prefixUrls = '', $displayTitlesAsAngularDirective = true)
public function getApiDocumentationAsString($outputExampleUrls = true)
{
if (!empty($prefixUrls)) {
$prefixUrls = 'http://demo.piwik.org/';
}

$str = $toc = '';

foreach (Proxy::getInstance()->getMetadata() as $class => $info) {
$moduleName = Proxy::getInstance()->getModuleNameFromClassName($class);
$rClass = new ReflectionClass($class);
list($toc, $str) = $this->generateDocumentation($outputExampleUrls, $prefixUrls = '', $displayTitlesAsAngularDirective = true);

if (!Piwik::hasUserSuperUserAccess() && $this->checkIfClassCommentContainsHideAnnotation($rClass)) {
continue;
}

if ($this->checkIfCommentContainsInternalAnnotation($rClass)) {
continue;
}

$toDisplay = $this->prepareModulesAndMethods($info, $moduleName);

foreach ($toDisplay as $moduleName => $methods) {
foreach ($methods as $index => $method) {
$reflectionMethod = new \ReflectionMethod($class, $method);
if ($this->checkIfCommentContainsInternalAnnotation($reflectionMethod)) {
unset($toDisplay[$moduleName][$index]);
}
}
if (empty($toDisplay[$moduleName])) {
unset($toDisplay[$moduleName]);
}
}

foreach ($toDisplay as $moduleName => $methods) {
$toc .= $this->prepareModuleToDisplay($moduleName);
$str .= $this->prepareMethodToDisplay($moduleName, $info, $methods, $class, $outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective);
}
}

if($displayTitlesAsAngularDirective) {
$str = "<div piwik-content-block content-title='Quick access to APIs' id='topApiRef' name='topApiRef'>
return "<div piwik-content-block content-title='Quick access to APIs' id='topApiRef' name='topApiRef'>
$toc</div>
$str";
} else {
$str = "<h2 id='topApiRef' name='topApiRef'>Quick access to APIs</h2>
}

/**
* Used on developer.piwik.org
*
* @param bool|true $outputExampleUrls
* @param string $prefixUrls
* @return string
*/
public function getApiDocumentationAsStringForDeveloperReference($outputExampleUrls = true, $prefixUrls = '')
{
list($toc, $str) = $this->generateDocumentation($outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective = false);

return "<h2 id='topApiRef' name='topApiRef'>Quick access to APIs</h2>
$toc
$str";
}

return $str;
}

public function prepareModuleToDisplay($moduleName)
protected function prepareModuleToDisplay($moduleName)
{
return "<a href='#$moduleName'>$moduleName</a><br/>";
}

public function prepareMethodToDisplay($moduleName, $info, $methods, $class, $outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective)
protected function prepareMethodToDisplay($moduleName, $info, $methods, $class, $outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective)
{
$str = '';
$str .= "\n<a name='$moduleName' id='$moduleName'></a>";
Expand Down Expand Up @@ -143,7 +111,7 @@ public function prepareMethodToDisplay($moduleName, $info, $methods, $class, $ou
return $str;
}

public function prepareModulesAndMethods($info, $moduleName)
protected function prepareModulesAndMethods($info, $moduleName)
{
$toDisplay = array();

Expand All @@ -157,7 +125,7 @@ public function prepareModulesAndMethods($info, $moduleName)
return $toDisplay;
}

public function addExamples($class, $methodName, $prefixUrls)
protected function addExamples($class, $methodName, $prefixUrls)
{
$token_auth = "&token_auth=" . Piwik::getCurrentUserTokenAuth();
$parametersToSet = array(
Expand All @@ -166,7 +134,6 @@ public function addExamples($class, $methodName, $prefixUrls)
'date' => Common::getRequestVar('date', 'today', 'string')
);
$str = '';
// used when we include this output in the Piwik official documentation for example
$str .= "<span class=\"example\">";
$exampleUrl = $this->getExampleUrl($class, $methodName, $parametersToSet);
if ($exampleUrl !== false) {
Expand Down Expand Up @@ -225,29 +192,6 @@ public function checkDocumentation($moduleToCheck)
return $moduleToCheck;
}

private function getInterfaceString($moduleName, $class, $info, $parametersToSet, $outputExampleUrls, $prefixUrls)
{
$str = '';

$str .= "\n<a name='$moduleName' id='$moduleName'></a><h2>Module " . $moduleName . "</h2>";
$str .= "<div class='apiDescription'> " . $info['__documentation'] . " </div>";
foreach ($info as $methodName => $infoMethod) {
if ($methodName == '__documentation') {
continue;
}

if (Proxy::getInstance()->isDeprecatedMethod($class, $methodName)) {
continue;
}

$str .= $this->getMethodString($moduleName, $class, $parametersToSet, $outputExampleUrls, $prefixUrls, $methodName, $str);
}

$str .= '<div style="margin:15px;"><a href="#topApiRef">↑ Back to top</a></div>';

return $str;
}

/**
* 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.
Expand Down Expand Up @@ -311,14 +255,6 @@ public function getExampleUrl($class, $methodName, $parametersToSet = array())

// we try to give an URL example to call the API
$aParameters = Proxy::getInstance()->getParametersList($class, $methodName);
// Kindly force some known generic parameters to appear in the final list
// the parameter 'format' can be set to all API methods (used in tests)
// the parameter 'hideIdSubDatable' is used for system tests only
// the parameter 'serialize' sets php outputs human readable, used in system tests and debug
// the parameter 'language' sets the language for the response (eg. country names)
// the parameter 'flat' reduces a hierarchical table to a single level by concatenating labels
// the parameter 'include_aggregate_rows' can be set to include inner nodes in flat reports
// the parameter 'translateColumnNames' can be set to translate metric names in csv/tsv exports
$aParameters['format'] = false;
$aParameters['hideIdSubDatable'] = false;
$aParameters['serialize'] = false;
Expand All @@ -327,15 +263,15 @@ public function getExampleUrl($class, $methodName, $parametersToSet = array())
$aParameters['label'] = false;
$aParameters['flat'] = false;
$aParameters['include_aggregate_rows'] = false;
$aParameters['filter_offset'] = false; //@review without adding this, I can not set filter_offset in $otherRequestParameters system tests
$aParameters['filter_limit'] = false; //@review without adding this, I can not set filter_limit in $otherRequestParameters system tests
$aParameters['filter_sort_column'] = false; //@review without adding this, I can not set filter_sort_column in $otherRequestParameters system tests
$aParameters['filter_sort_order'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_excludelowpop'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_excludelowpop_value'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_column_recursive'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_pattern'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_pattern_recursive'] = false; //@review without adding this, I can not set filter_sort_order in $otherRequestParameters system tests
$aParameters['filter_offset'] = false;
$aParameters['filter_limit'] = false;
$aParameters['filter_sort_column'] = false;
$aParameters['filter_sort_order'] = false;
$aParameters['filter_excludelowpop'] = false;
$aParameters['filter_excludelowpop_value'] = false;
$aParameters['filter_column_recursive'] = false;
$aParameters['filter_pattern'] = false;
$aParameters['filter_pattern_recursive'] = false;
$aParameters['filter_truncate'] = false;
$aParameters['hideColumns'] = false;
$aParameters['showColumns'] = false;
Expand Down Expand Up @@ -370,7 +306,7 @@ public function getExampleUrl($class, $methodName, $parametersToSet = array())
* @param string $name The method name
* @return string For example "(idSite, period, date = 'today')"
*/
public function getParametersString($class, $name)
protected function getParametersString($class, $name)
{
$aParameters = Proxy::getInstance()->getParametersList($class, $name);
$asParameters = array();
Expand All @@ -394,42 +330,47 @@ public function getParametersString($class, $name)
return "($sParameters)";
}

private function getMethodString($moduleName, $class, $parametersToSet, $outputExampleUrls, $prefixUrls, $methodName)
/**
* @param $outputExampleUrls
* @param $prefixUrls
* @param $displayTitlesAsAngularDirective
* @return array
*/
protected function generateDocumentation($outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective)
{
$str = '';
$token_auth = "&token_auth=" . Piwik::getCurrentUserTokenAuth();
$str = $toc = '';

$params = $this->getParametersString($class, $methodName);
$str .= "\n <div class='apiMethod'>- <b>$moduleName.$methodName </b>" . $params . "";
$str .= '<small>';

if ($outputExampleUrls) {
// we prefix all URLs with $prefixUrls
// used when we include this output in the Piwik official documentation for example
$str .= "<span class=\"example\">";
$exampleUrl = $this->getExampleUrl($class, $methodName, $parametersToSet);
if ($exampleUrl !== false) {
$lastNUrls = '';
if (preg_match('/(&period)|(&date)/', $exampleUrl)) {
$exampleUrlRss = $prefixUrls . $this->getExampleUrl($class, $methodName, array('date' => 'last10', 'period' => 'day') + $parametersToSet);
$lastNUrls = ", RSS of the last <a target='_blank' href='$exampleUrlRss&format=rss$token_auth&translateColumnNames=1'>10 days</a>";
}
$exampleUrl = $prefixUrls . $exampleUrl;
$str .= " [ Example in
<a target='_blank' href='$exampleUrl&format=xml$token_auth'>XML</a>,
<a target='_blank' href='$exampleUrl&format=JSON$token_auth'>Json</a>,
<a target='_blank' href='$exampleUrl&format=Tsv$token_auth&translateColumnNames=1'>Tsv (Excel)</a>
$lastNUrls
]";
} else {
$str .= " [ No example available ]";
foreach (Proxy::getInstance()->getMetadata() as $class => $info) {
$moduleName = Proxy::getInstance()->getModuleNameFromClassName($class);
$rClass = new ReflectionClass($class);

if (!Piwik::hasUserSuperUserAccess() && $this->checkIfClassCommentContainsHideAnnotation($rClass)) {
continue;
}
$str .= "</span>";
}

$str .= '</small>';
$str .= "</div>\n";
if ($this->checkIfCommentContainsInternalAnnotation($rClass)) {
continue;
}

return $str;
$toDisplay = $this->prepareModulesAndMethods($info, $moduleName);

foreach ($toDisplay as $moduleName => $methods) {
foreach ($methods as $index => $method) {
$reflectionMethod = new \ReflectionMethod($class, $method);
if ($this->checkIfCommentContainsInternalAnnotation($reflectionMethod)) {
unset($toDisplay[$moduleName][$index]);
}
}
if (empty($toDisplay[$moduleName])) {
unset($toDisplay[$moduleName]);
}
}

foreach ($toDisplay as $moduleName => $methods) {
$toc .= $this->prepareModuleToDisplay($moduleName);
$str .= $this->prepareMethodToDisplay($moduleName, $info, $methods, $class, $outputExampleUrls, $prefixUrls, $displayTitlesAsAngularDirective);
}
}
return array($toc, $str);
}
}
5 changes: 3 additions & 2 deletions plugins/API/Controller.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ function index()
public function listAllMethods()
{
$ApiDocumentation = new DocumentationGenerator();
return $ApiDocumentation->getAllInterfaceString($outputExampleUrls = true, $prefixUrls = Common::getRequestVar('prefixUrl', ''), $displayTitlesAsAngularDirective = false);
$prefixUrls = Common::getRequestVar('prefixUrl', 'http://demo.piwik.org/', 'string');
return $ApiDocumentation->getApiDocumentationAsStringForDeveloperReference($outputExampleUrls = true, $prefixUrls);
}

public function listAllAPI()
Expand All @@ -59,7 +60,7 @@ public function listAllAPI()

$ApiDocumentation = new DocumentationGenerator();
$view->countLoadedAPI = Proxy::getInstance()->getCountRegisteredClasses();
$view->list_api_methods_with_links = $ApiDocumentation->getAllInterfaceString();
$view->list_api_methods_with_links = $ApiDocumentation->getApiDocumentationAsString();
return $view->render();
}

Expand Down

0 comments on commit dae9b48

Please sign in to comment.