documentation updates

fixed  namespaces
add doygen generation, unhappy with phpDocumentor
develop
Sascha Nitsch 2024-07-17 15:45:19 +02:00
parent ed84e3be71
commit 6ea9c2728f
15 changed files with 3282 additions and 312 deletions

1
.gitignore vendored
View File

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

View File

@ -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

2854
Doxyfile Normal file

File diff suppressed because it is too large Load Diff

View File

@ -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
{
@ -225,14 +240,15 @@ class Api extends Main
*
* @param string $name
* parameter name
* @param array<string,mixed> $data
* @param array<string, mixed> $data
* array to update
* @param bool $int
* 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;
}

View File

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

View File

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

5
php/cache/cache.php vendored
View File

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

View File

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

View File

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

View File

@ -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;
@ -56,7 +61,7 @@ class Language {
}
if ($uselang === null && array_key_exists('HTTP_ACCEPT_LANGUAGE', $_SERVER)) {
$matches = array();
if (preg_match("/^(\S\S)\-/",$_SERVER['HTTP_ACCEPT_LANGUAGE'], $matches) == 1) {
if (preg_match("/^(\S\S)\-/", $_SERVER['HTTP_ACCEPT_LANGUAGE'], $matches) == 1) {
$language = $matches[1];
if (array_key_exists($language, $this->validLanguages)) {
$uselang = $language;
@ -64,7 +69,7 @@ class Language {
}
}
if ($uselang === null) {
$uselang = 'de';
$uselang = 'en';
}
$this->uselang = $uselang;
}
@ -80,16 +85,19 @@ 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");
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,10 +128,11 @@ 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");
require_once($_SERVER['DOCUMENT_ROOT'] . '/../lang/' . $this->uselang . "/$group.inc");
$this->lang[$group] = $l;
}
return array_keys($this->lang[$group]);
@ -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,11 +206,13 @@ 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) {
$counter[$language]=0;
$counter[$language] = 0;
}
foreach ($supported_languages as $language) {
for ($i = 0; $i < sizeof($wordList[$language]); ++$i) {
@ -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);
@ -238,20 +253,21 @@ class Language {
/**
* function called from smarty templates to print language translation
*
* @param array<string,mixed> $params
* @param array<string, mixed> $params
* smarty params, used are 'group', 'txt' and optionally 'var'
* @param \Smarty\Template $template
* 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);
}
}

View File

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

View File

@ -4,7 +4,7 @@
<paths>
<output>php-docs</output>
</paths>
<version number="develop">
<version number="latest">
<api format="php">
<visibility>internal</visibility>
<ignore>

View File

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

View File

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

View File

@ -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