documentation updates

fixed  namespaces
add doygen generation, unhappy with phpDocumentor

.gitignore

@@ -4,3 +4,4 @@ php/version.php
 php-docs
 .phpdoc
 phpdoc
+html

.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

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

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();
 }

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";
     }

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);
 }

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);
 }

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)
     {

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) {
+    public function __construct($uselang = null)
-    $this->lang = Array();
+    {
+        $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);
 }

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;

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>

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);
 }

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
+     * {@inheritDoc}
-     * @param string $_session session id
-     * @param string $_user user/profile name
-     * @return \Data\User | null
      */
-    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);
 }

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