show basic api doc in webinterface (top-menu - options - API help)

Signed-off-by: Michael Kaufmann (d00p) <d00p@froxlor.org>

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';
+}

apihelp.php

@@ -0,0 +1,112 @@
+<?php
+if (! defined('AREA'))
+	die('You cannot access this file directly!');
+
+/**
+ * This file is part of the Froxlor project.
+ * Copyright (c) 2018 the Froxlor Team (see authors).
+ *
+ * For the full copyright and license information, please view the COPYING
+ * file that was distributed with this source code. You can also view the
+ * COPYING file online at http://files.froxlor.org/misc/COPYING.txt
+ *
+ * @copyright (c) the authors
+ * @author Froxlor team <team@froxlor.org> (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 .= "<blockquote>";
+		$apihelp .= "<h3>" . ($funcdata['return_type'] == - 1 ? "<span class=\"red\">no-return-type</span>" : $funcdata['return_type']) . "&nbsp;";
+		$apihelp .= "<b>" . $module . ".<span class=\"blue\">" . $function . "</span></b></h3>";
+		// description
+		if (strtoupper(substr($funcdata['head'], 0, 4)) == "TODO")
+			$apihelp .= "<span class=\"red\">";
+		$apihelp .= $funcdata['head'];
+		if (strtoupper(substr($funcdata['head'], 0, 4)) == "TODO")
+			$apihelp .= "</span>";
+		// output ALL the params;
+		if (count($funcdata['params_list']) > 0) {
+			$parms = "<br><br><b>Parameters:</b><br><pre><ul>";
+			// separate and format them
+			foreach ($funcdata['params_list'] as $index => $param) {
+				$parms .= "<li>";
+				// check whether the parameter is optional
+				if (! empty($param['desc']) && strtolower(substr(trim($param['desc']), 0, 8)) == "optional") {
+					$parms .= "<i>optional</i>&nbsp;";
+					$param['desc'] = substr(trim($param['desc']), 8);
+					if (substr($param['desc'], 0, 1) == ',') {
+						$param['desc'] = substr(trim($param['desc']), 1);
+					}
+				}
+				$parms .= "<b>" . (strtolower($param['type']) == 'unknown' ? "<span class=\"red\">unknown</span>" : $param['type']) . "&nbsp;<span class=\"orange\">" . $param['name'] . "</span></b>";
+				if (! empty($param['desc'])) {
+					$parms .= "&nbsp;" . trim($param['desc']);
+				}
+				$parms .= "<li>";
+			}
+			$apihelp .= "</ul></pre>" . $parms;
+		}
+		$apihelp .= "</blockquote><br><br>";
+	}
+	$apihelp .= "<hr />";
+}
+
+eval("echo \"" . getTemplate("apihelp/index", 1) . "\";");

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';
+}

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))
+						if (empty($c)) {
-						continue;
+							continue;
-					if (! isset($result['head']) || empty($result['head'])) {
+						}
-						$result['head'] = $c . " ";
+						if ($param_desc) {
-					} else {
+							$result['params'][count($result['params']) - 1]['desc'] .= $c;
-						$result['head'] .= $c . " ";
+						} else {
+							if (! isset($result['head']) || empty($result['head'])) {
+								$result['head'] = $c . " ";
+							} else {
+								$result['head'] .= $c . " ";
+							}
+						}
 					}
 				}
 			}

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']

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';

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';

templates/Sparkle/apihelp/index.tpl

@@ -0,0 +1,13 @@
+$header
+	<article>
+		<h2>
+			API help
+		</h2>
+
+		<section>
+			<hr />
+			{$apihelp}		
+		</section>
+
+	</article>
+$footer

templates/Sparkle/header.tpl

@@ -67,6 +67,9 @@
 					<if Settings::Get('panel.allow_theme_change_customer') == '1' && $userinfo['adminsession'] == 0>
 						<li><a href="{$linker->getLink(array('section' => 'index', 'page' => 'change_theme'))}">{$lng['panel']['theme']}</a></li>
 					</if>
+					<if Settings::Get('api.enabled') == 1>
+						<li><a href="{$linker->getLink(array('section' => 'index', 'page' => 'apihelp'))}">{$lng['menue']['main']['apihelp']}</a></li>
+					</if>
 				</ul>
 			</li>
 			<li><a href="{$linker->getLink(array('section' => 'index', 'action' => 'logout'))}" class="logoutlink">{$lng['login']['logout']}</a></li>