documentation updates

fixed namespaces add doygen generation, unhappy with phpDocumentor
2024-07-17 15:45:19 +02:00 · 2024-07-17 15:45:19 +02:00 · 6ea9c2728f
parent ed84e3be71
commit 6ea9c2728f
15 changed files with 3282 additions and 312 deletions
--- a/.gitignore
+++ b/.gitignore
@ -4,3 +4,4 @@ php/version.php
 php-docs
 .phpdoc
 phpdoc
+html
--- a/.phan/config.php
+++ b/.phan/config.php
@ -49,7 +49,6 @@ return [
    //
    // Note that the **only** effect of choosing `'5.6'` is to infer that functions removed in php 7.0 exist.
    // (See `backward_compatibility_checks` for additional options)
-    // TODO: Choose a target_php_version for this project, or leave as null and remove this comment
    'target_php_version' => '8.3',

    // If enabled, missing properties will be created when
--- a/2854
+++ b/2854
--- a/php/api.php
+++ b/php/api.php
@ -13,16 +13,32 @@
 */
 class Api extends Main
 {
-    /** @var string called path */
+    /**
+     * called path
+     *
+     * @var string $path
+     */
    private $path;

-    /** @var array<string> path elements for the API call */
+    /**
+     * path elements for the API call
+     *
+     * @var array<string> $paths
+     * */
    private $paths;

-    /** @var Data\User current user */
+    /**
+     * current user
+     *
+     * @var Data\User $user
+     * */
    private $user;

-    /** @var int cache time default to 0 */
+    /**
+     * cache time default to 0
+     *
+     * @var int $cacheTime
+     */
    private $cacheTime = 0;

    /**
@ -59,7 +75,6 @@ class Api extends Main
        $this->openDatabase();
        $this->loadPlugins();
        $retval = "";
-        /** @var \Api\Api */
        $handler = null;
        if (!array_key_exists('HTTP_X_SESSION', $_SERVER) || !array_key_exists('HTTP_X_PROFILE', $_SERVER)) {
            http_response_code(403);
@ -148,7 +163,7 @@ class Api extends Main
     *          permission(s) to check for
     * @param string $exception Exception Type
     * @param string $message optional message
-     * @throws \Exceptions\PermissionDenied
+     * @throws Exceptions\PermissionDenied
     */
    public function checkPermission($permission, $exception = "\Exceptions\PermissionDenied", $message = null) : void
    {
@ -231,8 +246,9 @@ class Api extends Main
     *          is data an integer
     * @param string $altName
     *          optional alternative name in POST
+     * @return void
     */
-    public function updateString(string $name, array &$data, bool $int = false, string $altName = "") : void
+    public function updateString($name, &$data, $int = false, $altName = "")
    {
        if ($this->hasPost($altName ?: $name)) {
            $content = $this->escapePost($altName ?: $name, $int);
@ -244,8 +260,9 @@ class Api extends Main
     * set cache time
     *
     * @param int $time time in seconds
+     * @return void
     */
-    public function setCacheTime(int $time) : void
+    public function setCacheTime($time)
    {
        $this->cacheTime = $time;
    }
--- a/php/api/v1.php
+++ b/php/api/v1.php
@ -15,14 +15,15 @@ interface V1
 {
    /**
     * run given url path
-     * @param string[] $paths path array split by /
+     *
+     * @param array<string> $paths path array split by /
     * @return bool true on success
     */
-    public function exec($paths) : bool;
+    public function exec($paths);

    /**
     * get internal represenation as json string
     * @return string json string or html
     */
-    public function toJson() : string;
+    public function toJson();
 }
--- a/php/api/v1/dummy.php
+++ b/php/api/v1/dummy.php
@ -13,14 +13,23 @@ namespace Federator\Api\V1;
 */
 class Dummy implements \Federator\Api\V1
 {
-    /** @var \Main $main main instance */
+    /**
+     * \Federator\Main instance
+     *
+     * @var \Federator\Main $main
+     */
    private $main;

-    /** @var Array<string, string> $message internal message to output */
+    /**
+     * internal message to output
+     *
+     * @var Array<string, mixed> $message
+     */
    private $message = [];

    /**
     * constructor
+     *
     * @param \Main $main main instance
     */
    public function __construct(\Federator\Main $main)
@ -30,7 +39,8 @@ class Dummy implements \Federator\Api\V1

    /**
     * run given url path
-     * @param string[] $paths path array split by /
+     *
+     * @param array<string> $paths path array split by /
     * @return bool true on success
     */
    public function exec($paths) : bool
@ -60,8 +70,10 @@ class Dummy implements \Federator\Api\V1

    /**
     * get function for "/v1/dummy/moo"
+     *
+     * @return bool
     */
-    public function getDummy(): bool
+    public function getDummy()
    {
        $this->message = [
            'r1' => '             (__)       ',
@ -75,17 +87,20 @@ class Dummy implements \Federator\Api\V1

    /**
     * post function for /v1/dummy/moo"
+     *
+     * @return bool
     */
-    public function postDummy() : bool
+    public function postDummy()
    {
        return $this->getDummy();
    }

    /**
     * get internal represenation as json string
+     *
     * @return string json string
     */
-    public function toJson() : string
+    public function toJson()
    {
        return json_encode($this->message, JSON_PRETTY_PRINT) . "\n";
    }
--- a/php/cache/cache.php
+++ b/php/cache/cache.php
@ -17,7 +17,8 @@ interface Cache extends \Federator\Connector\Connector
     * save remote user by given session
     * @param string $_session session id
     * @param string $_user user/profile name
-     * @return \Federator\Data\User | null
+     * @aramm \Federator\Data\User $user user data
+     * @return void
     */
-    public function saveRemoteUserBySession(string $_session, string $_user, \Federator\Data\User $user);
+    public function saveRemoteUserBySession($_session, $_user, $user);
 }
--- a/php/connector/connector.php
+++ b/php/connector/connector.php
@ -17,7 +17,7 @@ interface Connector
     * get remote user by given session
     * @param string $_session session id
     * @param string $_user user/profile name
-     * @return \Federator\Data\User | null
+     * @return \Federator\Data\User | false
     */
    public function getRemoteUserBySession(string $_session, string $_user);
 }
--- a/php/data/user.php
+++ b/php/data/user.php
@ -13,16 +13,29 @@ namespace Federator\Data;
 */
 class User
 {
-    /** @var string user id */
+    /**
+     * user id
+     *
+     * @var string $id
+     */
    public $id;

    /* @var string user language */
    //public $lang;

-    /** @var array<string> user permissions */
+    /**
+     * user permissions
+     *
+     * @var array<string> $permissions
+     * @todo convert to enum
+     */
    public $permissions = [];

-    /** @var string session id */
+    /**
+     * session id
+     *
+     * @var string $session
+     * */
    public $session;

    /**
@ -31,6 +44,7 @@ class User
     *        permission to check
     *
     * @return bool true if user has permission, false if not
+     * @todo convert to ENUM
     */
    public function hasPermission(string $p)
    {
--- a/php/language.php
+++ b/php/language.php
@ -1,21 +1,23 @@
-<?php
+<?php
 /**
 * SPDX-FileCopyrightText: 2024 Sascha Nitsch (grumpydeveloper) https://contentnation.net/@grumpydevelop
 * SPDX-License-Identifier: GPL-3.0-or-later
 * @author Author: Sascha Nitsch (grumpydeveloper)
 */
-require_once '../vendor/autoload.php';
+
+namespace Federator;

 /**
 * Language abstraction class
 * @author Sascha Nitsch
 *
 */
-class Language {
-
+class Language
+{
    /**
     * list of valid languages
-   * @var array
+     *
+     * @var array $validLanguages
     */
    private $validLanguages = array(
        "de" => true,
@ -25,13 +27,15 @@ class Language {

    /**
     * language to use
-   * @var string
+     *
+     * @var string $uselang
     */
    private $uselang;

    /**
     * actual language data
-   * @var array<string,array<string,string>>
+     *
+     * @var array<string, array<string, string>> $lang
     */
    private $lang = [];

@ -41,8 +45,9 @@ class Language {
     * @param ?string $uselang
     *          use this language instead of autodetection, set to null if no preference
     */
-  function __construct($uselang = null) {
-    $this->lang = Array();
+    public function __construct($uselang = null)
+    {
+        $this->lang = [];
        if ($uselang !== null) {
            if (! array_key_exists($uselang, $this->validLanguages)) {
                $uselang = null;
@ -64,7 +69,7 @@ class Language {
            }
        }
        if ($uselang === null) {
-      $uselang = 'de';
+            $uselang = 'en';
        }
        $this->uselang = $uselang;
    }
@ -80,14 +85,17 @@ class Language {
     *          optional values to replace
     * @return string translated string
     */
-  function printlang($group, $key, array $values = array()) {
+    public function printlang($group, $key, array $values = array())
+    {
        if ($this->uselang === 'xy') {
            return "$group:$key";
        }
        if (! isset($this->lang[$group])) {
            $l = [];
            $root = $_SERVER['DOCUMENT_ROOT'];
-      if ($root === '') $root = '.';
+            if ($root === '') {
+                $root = '.';
+            }
            if (@file_exists($root . '/../lang/' . $this->uselang . "/$group.inc")) {
                require($root . '/../lang/' . $this->uselang . "/$group.inc");
                $this->lang[$group] = $l;
@ -104,7 +112,6 @@ class Language {
            }
            return $string;
        }
-
        $basedir = $_SERVER['DOCUMENT_ROOT'] . '/../';
        $fh = @fopen("$basedir/logs/missingtrans.txt", 'a');
        if ($fh !== false) {
@ -114,7 +121,6 @@ class Language {
        return "&gt;&gt;$group:$key&lt;&lt;";
    }

-
    /**
     * get keys (valid ids) of a named group
     *
@ -122,7 +128,8 @@ class Language {
     *          group name to fetch keys
     * @return array<string> list of keys
     */
-  function getKeys(string $group) {
+    public function getKeys(string $group)
+    {
        if (! isset($this->lang[$group])) {
            $l = [];
            require_once($_SERVER['DOCUMENT_ROOT'] . '/../lang/' . $this->uselang . "/$group.inc");
@ -136,17 +143,21 @@ class Language {
     *
     * @return string current language
     */
-  function getLang() {
+    public function getLang()
+    {
        return $this->uselang;
    }

    /**
     * guess langauge of text
-   * @param string $text
-   * @param string $default
+     *
+     * @param string $text input text
+     * @param string $default default language
+     * @param bool $debug debug flag
     * @return string detected language
     */
-  static function guessLanguage(string $text, string $default, bool $debug = false) {
+    public static function guessLanguage($text, $default, $debug = false)
+    {
        $supported_languages = array(
            'en',
            'de',
@ -177,6 +188,7 @@ class Language {
            'we', 'say', 'her', 'she', 'or', 'an', 'will', 'my', 'one', 'all',
            'would', 'there', 'their', 'what', 'so', 'up', 'out', 'if', 'about'
        );
+
        // French word list
        // from https://1000mostcommonwords.com/1000-most-common-french-words/
        /*$wordList['fr'] = array ('comme', 'que',  'tait',  'pour',  'sur',  'sont',  'avec',
@ -194,7 +206,9 @@ class Language {
        // case in your language wordlists!
        $txt = strip_tags($text);
        $txt = preg_replace("/[^A-Za-z:\\/\\.]+/", ' ', $txt);
-    if ($debug) echo "text: '$txt'\n";
+        if ($debug) {
+            echo "text: '$txt'\n";
+        }
        $counter = [];
        // count the occurrences of the most frequent words
        foreach ($supported_languages as $language) {
@ -209,8 +223,9 @@ class Language {
                $counter[$language] += $count;
            }
        }
-    if ($debug)
+        if ($debug) {
            print_r($counter);
+        }
        // get max counter value
        $max = max($counter);
        $maxs = array_keys($counter, $max);
@ -244,14 +259,15 @@ class Language {
 *          template instance
 * @return string translated text
 */
-function smarty_function_printlang($params, $template) : string {
+function smarty_function_printlang($params, $template) : string
+{
    $lang = $template->getTemplateVars("language");
    <<<'PHAN'
      @phan-var \Language $lang
      PHAN;
    $forcelang = array_key_exists('lang', $params) ? $params['lang'] : null;
    if ($forcelang !== null) {
-    $lang = new \Language($forcelang);
+        $lang = new Language($forcelang);
    }
    if (isset($params['var'])) {
        return $lang->printlang($params['group'], $params['key'], $params['var']);
@ -269,28 +285,14 @@ function smarty_function_printlang($params, $template) : string {
 *          template instance
 * @return string translated text as JS line
 */
-function smarty_function_printjslang($params, $template) : string {
+function smarty_function_printjslang($params, $template) : string
+{
    $lang = $template->getTemplateVars("language");
    $prefix = 'window.translations.' . $params['group'] . '.' . $params['key'] . ' = \'';
    $postfix = '\';';
-  if (isset($params['var']))
+    if (isset($params['var'])) {
        return $prefix . $lang->printlang($params['group'], $params['key'], $params['var']) . $postfix;
-  else
+    } else {
        return $prefix . $lang->printlang($params['group'], $params['key']) . $postfix;
    }
-
-/**
- * print translation of given group and id, optionally using variables
- *
- * @param string $group
- *          group name
- * @param string $key
- *          string name
- * @param array<mixed> $values
- *          optional values to replace
- * @return string translated string
- */
-function printlang(string  $group, string $key, array $values=array()) {
-  global $contentnation;
-  return $contentnation->translate(null, $group, $key, $values);
 }
--- a/php/main.php
+++ b/php/main.php
@ -9,30 +9,70 @@
 namespace Federator;

 /**
- * Base class for ContentNation and Api
+ * Base class for Api and related classes
 * @author Sascha Nitsch
 */
 class Main
 {
-    /** @var Cache\Cache cache instance */
+    /**
+     * cache instance
+     *
+     * @var Cache\Cache $cache
+     */
    protected $cache;
-    /** @var array<string,mixed> current config */
+    /**
+     * current config
+     *
+     * @var array<string,mixed>  $config
+     */
    protected $config;
-    /** @var Connector\Connector remote connector */
+    /**
+     * remote connector
+     *
+     * @var Connector\Connector $connector
+     */
    protected $connector = null;
-    /** @var string response content type */
+    /**
+     * response content type
+     *
+     * @var string $contentType
+     */
    protected $contentType = "text/html";
-    /** @var \Mysqli database instance */
+    /**
+     * database instance
+     *
+     * @var \Mysqli $dbh
+     */
    protected $dbh;
-    /** @var array<string,string> extra headers */
+    /**
+     * extra headers
+     *
+     * @var array<string,string>  $headers
+     */
    protected $headers = [];
-    /** @var \Language languange instance */
+    /**
+     * languange instance
+     *
+     * @var \Language $lang
+     */
    protected $lang = null;
-    /** @var ?string redirect URL */
+    /**
+     * redirect URL
+     *
+     * @var ?string $redirect
+     */
    protected $redirect = null;
-    /** @var int response code */
+    /**
+     * response code
+     *
+     * @var int $responseCode
+     */
    protected $responseCode = 200;
-    /** @var \Smarty\Smarty|null smarty instance */
+    /**
+     * smarty instance
+     *
+     * @var \Smarty\Smarty|null $smarty
+     */
    protected $smarty;

    /**
@ -152,7 +192,7 @@ class Main
        }
        if ($this->lang !== null) {
            if ($this->lang->getLang() !== $lang) {
-                $l = new \Language($lang);
+                $l = new Language($lang);
                return $l->printlang($group, $key, $parameters);
            }
            return $this->lang->printlang($group, $key, $parameters);
@ -168,7 +208,7 @@ class Main
     */
    public function validLanguage(?string $lang) : bool
    {
-        $language = new \Language($lang);
+        $language = new Language($lang);
        if ($language->getLang() === $lang) {
            $this->lang = $language;
            return true;
--- a/phpdoc.dist.xml
+++ b/phpdoc.dist.xml
@ -4,7 +4,7 @@
    <paths>
        <output>php-docs</output>
    </paths>
-    <version number="develop">
+    <version number="latest">
        <api format="php">
            <visibility>internal</visibility>
            <ignore>
--- a/plugins/dummyconnector.php
+++ b/plugins/dummyconnector.php
@ -5,12 +5,12 @@
 * @author Author: Sascha Nitsch (grumpydeveloper)
 **/

-namespace Federator;
+namespace Federator\Connector;

 /**
 * dummy connector that always return the same permission
 */
-class DummyConnector implements Connector\Connector
+class DummyConnector implements Connector
 {
    /**
     * constructor
@ -28,7 +28,7 @@ class DummyConnector implements Connector\Connector
    public function getRemoteUserBySession(string $_session, string $_user)
    {
        // validate $_session and $user
-        $user = new Data\User();
+        $user = new \Federator\Data\User();
        $user->id = $_user;
        $user->permissions = ['PUBLISH'];
        $user->session = $_session;
@ -36,8 +36,16 @@ class DummyConnector implements Connector\Connector
    }
 }

-function dummy_load(Main $main)
+namespace Federator;
+
+/**
+ * Function to initialize plugin
+ *
+ * @param  \Federator\Main $main main instance
+ * @return void
+ */
+function dummy_load($main)
 {
-    $dummy = new DummyConnector();
+    $dummy = new Connector\DummyConnector();
    $main->setConnector($dummy);
 }
--- a/plugins/rediscache.php
+++ b/plugins/rediscache.php
@ -13,30 +13,45 @@ namespace Federator\Cache;
 */
 class RedisCache implements Cache
 {
-    /** @var \Redis connection handle */
+    /**
+     * connection handle
+     *
+     * @var \Redis $redis
+     */
    private $redis;

+    /**
+     * constructor
+     */
    public function __construct()
    {
    }

    /**
-     * get remote user by given session
-     * @param string $_session session id
-     * @param string $_user user/profile name
-     * @return \Data\User | null
+     * {@inheritDoc}
     */
-    public function getRemoteUserBySession(string $_session, string $_user)
+    public function getRemoteUserBySession($_session, $_user)
    {
    }

-    public function saveRemoteUserBySession(string $_session, string $_user, \Federator\Data\User $user)
+    /**
+     * {@inheritDoc}
+     */
+    public function saveRemoteUserBySession($_session, $_user, $user)
    {
    }
 }

-function dummy_rediscache(\Federator\Main $main)
+namespace Federator;
+
+/**
+ * Function to initialize plugin
+ *
+ * @param  \Federator\Main $main main instance
+ * @return void
+ */
+function rediscache_load($main)
 {
-    $rc = new RedisCache();
+    $rc = new Cache\RedisCache();
    $main->setCache($rc);
 }
--- a/release.sh
+++ b/release.sh
@ -1 +1,4 @@
+#!/bin/bash
 git log | head -n1 | awk '{print "<?php\nglobal $version;\n$version=\"" $2 "\";\n"}' > php/version.php
+vendor/phan/phan/phan
+./phpdoc