add help to web interface

Lib/Formatter/Html.php

@@ -130,10 +130,15 @@ class Html extends Formatter {
                 'status' => 'info',
             );
         }
-        $data = Logger::data();
-        $context['time'] = $data['time'];
+        $info = Logger::data();
+        $context['time'] = $info['time'];
 
         $panel = static::template($context, 'panel');
+
+        if(isset($data['extra'])) {
+            $panel .= $data['extra'];
+        }
+
         echo static::template(array(
             'title' => $context['title'],
             'content' => $panel,

Lib/Help.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace BSR\Lib;
+
+use BSR\Lib\Exception\WebException;
+use BSR\Lib\Formatter\Html;
+
+class Help {
+    private static function func($ws, $func) {
+        $rm = new \ReflectionMethod($ws, $func);
+
+        $doc = $rm->getDocComment();
+        $params = $rm->getParameters();
+
+        preg_match_all('/@param\s+(?P<type>[^\s]*?)\s*\$(?P<name>[^\s]+?)\s+(?P<doc>[\w\s]*)/', $doc, $parametersDoc, PREG_SET_ORDER);
+        preg_match('/@return\s+(?P<type>[^\s]*?)\s+(?P<doc>[\w\s]*)/', $doc, $returnDoc);
+
+        $doc = array_filter(array_map(function($l) {
+            $l = trim($l, " \t\n\r\0\x0B");
+            if(strpos($l, '/**') === 0 || strpos($l, '*/') === 0) {
+                $l = '';
+            }
+            $l = trim($l, "* ");
+            if(strpos($l, '@') === 0) {
+                $l = '';
+            }
+            return $l;
+        }, explode("\n", $doc)));
+        $doc = nl2br(implode("\n", $doc));
+
+        $paramsHtml = '';
+        foreach($params as $p) {
+            foreach($parametersDoc as $d) {
+                if(isset($d['name']) && $p->name == $d['name']) {
+                    $paramsHtml .= Html::template(array(
+                        'name' => $p->name,
+                        'optional' => $p->isDefaultValueAvailable() ? '(optional)' : '',
+                        'type' => isset($d['type']) ? $d['type'] : '',
+                        'doc' => isset($d['doc']) ? $d['doc'] : '',
+                    ), 'param_help');
+                }
+            }
+        }
+
+        return Html::template(array(
+            'func' => $func,
+            'help' => $doc,
+            'parameters' => $paramsHtml,
+            'return' => Html::template(array(
+                'type' => isset($returnDoc['type']) ? $returnDoc['type'] : '',
+                'doc' => isset($returnDoc['doc']) ? $returnDoc['doc'] : '',
+            ), 'return_help'),
+        ), 'func_help');
+    }
+
+
+    public static function content(WebService $ws) {
+        $rc = new \ReflectionClass($ws);
+
+        $methods = array_filter(array_map(function(\ReflectionMethod $m) {
+            if($m->getName() == 'Run') {
+                // this is a method from WebService directly and is of not interests for the help
+                return '';
+            }
+            return $m->getName();
+        }, $rc->getMethods(\ReflectionMethod::IS_PUBLIC)));
+
+        $html = '';
+        foreach($methods as $m) {
+            $html .= static::func($ws, $m);
+        }
+
+        return $html;
+    }
+
+    public static function exception(WebException $e, WebService $ws, $func) {
+        return static::func($ws, $func);
+    }
+}

Lib/WebService.php

@@ -31,6 +31,9 @@ abstract class WebService
             $data["error"]["code"] = $e->getCode();
             $data["error"]["reason"] = $e->getMessage();
             $data["error"]["name"] = $e->getName();
+
+            $data['extra'] = Help::exception($e, $this, $this->func);
+
             $this->status = 400;
 
             Logger::info($e->getName(), 'error');

help.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace BSR;
+
+use BSR\Lib\Formatter\Html;
+use BSR\Lib\Help;
+
+require_once('Lib/autoloader.php');
+
+echo Html::template(array(
+    'title' => 'Help',
+    'content' => Help::content(new NetBiblio()),
+));

templates/func_help.html

@@ -0,0 +1,14 @@
+<h2>{{ func }}</h2>
+
+<h3>Parameters</h3>
+<dl>
+    {{ parameters }}
+</dl>
+
+<h3>Return</h3>
+{{ return }}
+
+<h3>Description</h3>
+{{ help }}
+
+

templates/layout.html

@@ -22,7 +22,7 @@
 
             <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
                 <ul class="nav navbar-nav">
-                    <li><a href="/">Help</a></li>
+                    <li><a href="help.php">Help</a></li>
                     <li><a href="logs.php">Logs</a></li>
                     <li><a href="phpinfo.php">PHPInfo</a></li>
                 </ul>

templates/param_help.html

@@ -0,0 +1,5 @@
+<dt>{{ name }} {{ optional }}</dt>
+<dd>
+    <bold>{{ type }}</bold>
+    {{ doc }}
+</dd>

templates/return_help.html

@@ -0,0 +1,2 @@
+<bold>{{ type }}</bold>
+{{ doc }}