From b42a7b1b26d434b41626a3ac2db8637f69e5c2be Mon Sep 17 00:00:00 2001 From: "Michael Kaufmann (d00p)" Date: Thu, 22 Feb 2018 13:41:28 +0100 Subject: [PATCH] show basic api doc in webinterface (top-menu - options - API help) Signed-off-by: Michael Kaufmann (d00p) --- admin_index.php | 4 + apihelp.php | 112 +++++++++++++++++++++ customer_index.php | 3 + lib/classes/api/commands/class.Froxlor.php | 30 ++++-- lib/navigation/00.froxlor.main.php | 10 ++ lng/english.lng.php | 3 + lng/german.lng.php | 3 + templates/Sparkle/apihelp/index.tpl | 13 +++ templates/Sparkle/header.tpl | 3 + 9 files changed, 171 insertions(+), 10 deletions(-) create mode 100644 apihelp.php create mode 100644 templates/Sparkle/apihelp/index.tpl diff --git a/admin_index.php b/admin_index.php index 174f65a0..959a4632 100644 --- a/admin_index.php +++ b/admin_index.php @@ -51,6 +51,7 @@ if (isset($_POST['id'])) { } if ($page == 'overview') { + $log->logAction(ADM_ACTION, LOG_NOTICE, "viewed admin_index"); $overview_stmt = Database::prepare("SELECT COUNT(*) AS `number_customers`, SUM(`diskspace_used`) AS `diskspace_used`, @@ -404,3 +405,6 @@ if ($page == 'overview') { redirectTo($filename, array('s' => $s)); } } +elseif ($page == 'apihelp' && Settings::Get('api.enabled') == 1) { + require_once __DIR__ . '/apihelp.php'; +} diff --git a/apihelp.php b/apihelp.php new file mode 100644 index 00000000..2f426f3a --- /dev/null +++ b/apihelp.php @@ -0,0 +1,112 @@ + (2018-) + * @license GPLv2 http://files.froxlor.org/misc/COPYING.txt + * @package Panel + * @since 0.10.0 + * + */ + +// This file is being included in admin_index and customer_index +// and therefore does not need to require lib/init.php + +try { + $json_result = Froxlor::getLocal($userinfo)->listFunctions(); +} catch (Exception $e) { + dynamic_error($e->getMessage()); +} +$result = json_decode($json_result, true)['data']; + +// get response data +$m_arr = $result; + +// initialize output-array +$output_arr = array(); + +// check every module +foreach ($m_arr as $module) { + + // initialize module array for sorting + if (! isset($output_arr[$module['module']]) || ! is_array($output_arr[$module['module']])) { + $output_arr[$module['module']] = array(); + } + + // set necessary data + $output_arr[$module['module']][$module['function']] = array( + 'return_type' => (isset($module['return']['type']) && $module['return']['type'] != "" ? $module['return']['type'] : - 1), + 'params_list' => array(), + 'head' => $module['head'] + ); + + if (isset($module['params']) && is_array($module['params'])) { + foreach ($module['params'] as $param) { + $output_arr[$module['module']][$module['function']]['params_list'][] = array( + 'type' => $param['type'], + 'name' => $param['parameter'], + 'desc' => $param['desc'] + ); + } + } +} + +// sort array +ksort($output_arr); + +$apihelp = ""; + +// output ALL the modules +foreach ($output_arr as $module => $functions) { + + // sort by function + ksort($functions); + + // output ALL the functions + foreach ($functions as $function => $funcdata) { + $apihelp .= "
"; + $apihelp .= "

" . ($funcdata['return_type'] == - 1 ? "no-return-type" : $funcdata['return_type']) . " "; + $apihelp .= "" . $module . "." . $function . "

"; + // description + if (strtoupper(substr($funcdata['head'], 0, 4)) == "TODO") + $apihelp .= ""; + $apihelp .= $funcdata['head']; + if (strtoupper(substr($funcdata['head'], 0, 4)) == "TODO") + $apihelp .= ""; + // output ALL the params; + if (count($funcdata['params_list']) > 0) { + $parms = "

Parameters:
    ";
+			// separate and format them
+			foreach ($funcdata['params_list'] as $index => $param) {
+				$parms .= "
  • ";
+				// check whether the parameter is optional
+				if (! empty($param['desc']) && strtolower(substr(trim($param['desc']), 0, 8)) == "optional") {
+					$parms .= "optional ";
+					$param['desc'] = substr(trim($param['desc']), 8);
+					if (substr($param['desc'], 0, 1) == ',') {
+						$param['desc'] = substr(trim($param['desc']), 1);
+					}
+				}
+				$parms .= "" . (strtolower($param['type']) == 'unknown' ? "unknown" : $param['type']) . " " . $param['name'] . "";
+				if (! empty($param['desc'])) {
+					$parms .= " " . trim($param['desc']);
+				}
+				$parms .= "
  • ";
+			}
+			$apihelp .= "
" . $parms; + } + $apihelp .= "


"; + } + $apihelp .= "
"; +} + +eval("echo \"" . getTemplate("apihelp/index", 1) . "\";"); diff --git a/customer_index.php b/customer_index.php index bb1305c9..71877c71 100644 --- a/customer_index.php +++ b/customer_index.php @@ -319,3 +319,6 @@ if ($page == 'overview') { redirectTo($filename, array('s' => $s)); } } +elseif ($page == 'apihelp' && Settings::Get('api.enabled') == 1) { + require_once __DIR__ . '/apihelp.php'; +} diff --git a/lib/classes/api/commands/class.Froxlor.php b/lib/classes/api/commands/class.Froxlor.php index b005634c..99a49a28 100644 --- a/lib/classes/api/commands/class.Froxlor.php +++ b/lib/classes/api/commands/class.Froxlor.php @@ -20,7 +20,7 @@ class Froxlor extends ApiCommand /** * checks whether there is a newer version of froxlor available - * + * * @throws Exception * @return string */ @@ -178,6 +178,7 @@ class Froxlor extends ApiCommand $clines = explode("\n", $comment); $result = array(); $result['params'] = array(); + $param_desc = false; foreach ($clines as $c) { $c = trim($c); // check param-section @@ -189,6 +190,7 @@ class Froxlor extends ApiCommand 'type' => $r[1], 'desc' => (isset($r[3]) ? trim($r['3']) : '') ); + $param_desc = true; } // check return-section elseif (strpos($c, '@return')) { preg_match('/^\*\s\@return\s(\w+)(\s.*)?/', $c, $r); @@ -201,18 +203,26 @@ class Froxlor extends ApiCommand 'desc' => (isset($r[2]) ? trim($r[2]) : '') ); } else if (! empty($c) && strpos($c, '@throws') === false) { - if (substr($c, 0, 3) == "/**") + if (substr($c, 0, 3) == "/**") { continue; - if (substr($c, 0, 2) == "*/") + } + if (substr($c, 0, 2) == "*/") { continue; - if (substr($c, 0, 1) == "*") + } + if (substr($c, 0, 1) == "*") { $c = trim(substr($c, 1)); - if (empty($c)) - continue; - if (! isset($result['head']) || empty($result['head'])) { - $result['head'] = $c . " "; - } else { - $result['head'] .= $c . " "; + if (empty($c)) { + continue; + } + if ($param_desc) { + $result['params'][count($result['params']) - 1]['desc'] .= $c; + } else { + if (! isset($result['head']) || empty($result['head'])) { + $result['head'] = $c . " "; + } else { + $result['head'] .= $c . " "; + } + } } } } diff --git a/lib/navigation/00.froxlor.main.php b/lib/navigation/00.froxlor.main.php index a02a3a07..61c7fe6f 100644 --- a/lib/navigation/00.froxlor.main.php +++ b/lib/navigation/00.froxlor.main.php @@ -38,6 +38,11 @@ return array( 'label' => $lng['menue']['main']['changetheme'], 'show_element' => (Settings::Get('panel.allow_theme_change_customer') == true) ), + array( + 'url' => 'customer_index.php?page=apihelp', + 'label' => $lng['menue']['main']['apihelp'], + 'show_element' => (Settings::Get('api.enabled') == true) + ), array( 'url' => 'customer_index.php?action=logout', 'label' => $lng['login']['logout'] @@ -179,6 +184,11 @@ return array( 'label' => $lng['menue']['main']['changetheme'], 'show_element' => (Settings::Get('panel.allow_theme_change_admin') == true) ), + array( + 'url' => 'admin_index.php?page=apihelp', + 'label' => $lng['menue']['main']['apihelp'], + 'show_element' => (Settings::Get('api.enabled') == true) + ), array( 'url' => 'admin_index.php?action=logout', 'label' => $lng['login']['logout'] diff --git a/lng/english.lng.php b/lng/english.lng.php index 8adc8a40..b0f87d35 100644 --- a/lng/english.lng.php +++ b/lng/english.lng.php @@ -2119,4 +2119,7 @@ $lng['admin']['plans']['use_plan'] = 'Apply plan'; $lng['question']['plan_reallydelete'] = 'Do you really want to delete the hosting plan %s?'; $lng['admin']['notryfiles']['title'] = 'No autogenerated try_files'; $lng['admin']['notryfiles']['description'] = 'Say yes here if you want to specify a custom try_files directive in specialsettings (needed for some wordpress plugins for example).'; + +// added in froxlor 0.10.0 $lng['panel']['none_value'] = 'None'; +$lng['menue']['main']['apihelp'] = 'API help'; diff --git a/lng/german.lng.php b/lng/german.lng.php index 888303b1..4693d860 100644 --- a/lng/german.lng.php +++ b/lng/german.lng.php @@ -1769,4 +1769,7 @@ $lng['admin']['plans']['use_plan'] = 'Plan übernehmen'; $lng['question']['plan_reallydelete'] = 'Wollen Sie den Hosting-Plan "%s" wirklich löschen?'; $lng['admin']['notryfiles']['title'] = 'Keine generierte try_files Anweisung'; $lng['admin']['notryfiles']['description'] = 'Wähle "Ja", wenn eine eigene try_files Direktive in den "eigenen Vhost Einstellungen" angegeben werden soll (z.B. nötig für manche Wordpress Plugins).'; + +// added in froxlor 0.10.0 $lng['panel']['none_value'] = 'Keine'; +$lng['menue']['main']['apihelp'] = 'API Hilfe'; diff --git a/templates/Sparkle/apihelp/index.tpl b/templates/Sparkle/apihelp/index.tpl new file mode 100644 index 00000000..793a57a8 --- /dev/null +++ b/templates/Sparkle/apihelp/index.tpl @@ -0,0 +1,13 @@ +$header +
+

+ API help +

+ +
+
+ {$apihelp} +
+ +
+$footer diff --git a/templates/Sparkle/header.tpl b/templates/Sparkle/header.tpl index 2909fc6d..d858f52c 100644 --- a/templates/Sparkle/header.tpl +++ b/templates/Sparkle/header.tpl @@ -67,6 +67,9 @@
  • {$lng['panel']['theme']}
    •  + +
  • {$lng['menue']['main']['apihelp']}
    • +
  • {$lng['login']['logout']}