From 1a737be2b408135177a9e94dcffd0f68c0aca90b Mon Sep 17 00:00:00 2001 From: Klaus Weidenbach Date: Tue, 5 Sep 2017 00:23:42 +0200 Subject: :bulb: Improving Doxygen documentation. Fix some Doxygen parsing errors. Improve hooks documentation. --- Zotlabs/Lib/ActivityStreams.php | 124 ++++++++++++++++++++++++++++++++-------- Zotlabs/Lib/Chatroom.php | 40 +++++++------ Zotlabs/Lib/Config.php | 29 +++++----- Zotlabs/Lib/PConfig.php | 46 ++++++++------- Zotlabs/Lib/SConfig.php | 7 ++- Zotlabs/Lib/XConfig.php | 33 ++++++++--- 6 files changed, 193 insertions(+), 86 deletions(-) (limited to 'Zotlabs/Lib') diff --git a/Zotlabs/Lib/ActivityStreams.php b/Zotlabs/Lib/ActivityStreams.php index 379e78a59..2e9bb0703 100644 --- a/Zotlabs/Lib/ActivityStreams.php +++ b/Zotlabs/Lib/ActivityStreams.php @@ -2,6 +2,11 @@ namespace Zotlabs\Lib; +/** + * @brief ActivityStreams class. + * + * Parses an ActivityStream JSON string. + */ class ActivityStreams { public $data; @@ -19,9 +24,16 @@ class ActivityStreams { public $recips = null; public $raw_recips = null; + /** + * @brief Constructor for ActivityStreams. + * + * Takes a JSON string as parameter, decodes it and sets up this object. + * + * @param string $string + */ function __construct($string) { - $this->data = json_decode($string,true); + $this->data = json_decode($string, true); if($this->data) { $this->valid = true; } @@ -50,6 +62,11 @@ class ActivityStreams { } } + /** + * @brief Return if instantiated ActivityStream is valid. + * + * @return boolean Return true if the JSON string could be decoded. + */ function is_valid() { return $this->valid; } @@ -58,18 +75,26 @@ class ActivityStreams { $this->saved_recips = $arr; } - function collect_recips($base = '',$namespace = '') { + /** + * @brief Collects all recipients. + * + * @param string $base + * @param string $namespace (optional) default empty + * @return array + */ + function collect_recips($base = '', $namespace = '') { $x = []; - $fields = [ 'to','cc','bto','bcc','audience']; + $fields = [ 'to', 'cc', 'bto', 'bcc', 'audience']; foreach($fields as $f) { - $y = $this->get_compound_property($f,$base,$namespace); + $y = $this->get_compound_property($f, $base, $namespace); if($y) { - $x = array_merge($x,$y); + $x = array_merge($x, $y); if(! is_array($this->raw_recips)) $this->raw_recips = []; + $this->raw_recips[$f] = $x; } - } + } // not yet ready for prime time // $x = $this->expand($x,$base,$namespace); return $x; @@ -96,23 +121,30 @@ class ActivityStreams { } } - // @fixme de-duplicate + /// @fixme de-duplicate return $ret; } - function get_namespace($base,$namespace) { + /** + * @brief + * + * @param array $base + * @param string $namespace if not set return empty string + * @return string|NULL + */ + function get_namespace($base, $namespace) { if(! $namespace) return ''; $key = null; - foreach( [ $this->data, $base ] as $b ) { if(! $b) continue; - if(array_key_exists('@context',$b)) { + + if(array_key_exists('@context', $b)) { if(is_array($b['@context'])) { foreach($b['@context'] as $ns) { if(is_array($ns)) { @@ -135,19 +167,35 @@ class ActivityStreams { } } } + return $key; } - - function get_property_obj($property,$base = '',$namespace = '' ) { - $prefix = $this->get_namespace($base,$namespace); + /** + * @brief + * + * @param string $property + * @param array $base (optional) + * @param string $namespace (optional) default empty + * @return NULL|mixed + */ + function get_property_obj($property, $base = '', $namespace = '') { + $prefix = $this->get_namespace($base, $namespace); if($prefix === null) - return null; + return null; + $base = (($base) ? $base : $this->data); $propname = (($prefix) ? $prefix . ':' : '') . $property; - return ((array_key_exists($propname,$base)) ? $base[$propname] : null); + + return ((array_key_exists($propname, $base)) ? $base[$propname] : null); } + /** + * @brief Fetches a property from an URL. + * + * @param string $url + * @return NULL|mixed + */ function fetch_property($url) { $redirects = 0; if(! check_siteallowed($url)) { @@ -155,44 +203,70 @@ class ActivityStreams { return null; } - $x = z_fetch_url($url,true,$redirects, + $x = z_fetch_url($url, true, $redirects, ['headers' => [ 'Accept: application/ld+json; profile="https://www.w3.org/ns/activitystreams", application/activity+json' ]]); if($x['success']) - return json_decode($x['body'],true); + return json_decode($x['body'], true); + return null; } - function get_compound_property($property,$base = '',$namespace = '') { - $x = $this->get_property_obj($property,$base,$namespace); + /** + * @brief + * + * @param string $property + * @param array $base + * @param string $namespace (optional) default empty + * @return NULL|mixed + */ + function get_compound_property($property, $base = '', $namespace = '') { + $x = $this->get_property_obj($property, $base, $namespace); if($this->is_url($x)) { - $x = $this->fetch_property($x); + $x = $this->fetch_property($x); } + return $x; } + /** + * @brief Check if string starts with http. + * + * @param string $url + * @return boolean + */ function is_url($url) { - if(($url) && (! is_array($url)) && (strpos($url,'http') === 0)) { + if(($url) && (! is_array($url)) && (strpos($url, 'http') === 0)) { return true; } + return false; } - function get_primary_type($base = '',$namespace = '') { + /** + * @brief Gets the type property. + * + * @param array $base + * @param string $namespace (optional) default empty + * @return NULL|mixed + */ + function get_primary_type($base = '', $namespace = '') { if(! $base) $base = $this->data; - $x = $this->get_property_obj('type',$base,$namespace); + + $x = $this->get_property_obj('type', $base, $namespace); if(is_array($x)) { foreach($x as $y) { - if(strpos($y,':') === false) { + if(strpos($y, ':') === false) { return $y; } } } + return $x; } function debug() { - $x = var_export($this,true); + $x = var_export($this, true); return $x; } diff --git a/Zotlabs/Lib/Chatroom.php b/Zotlabs/Lib/Chatroom.php index e1a9a10b3..e762620ae 100644 --- a/Zotlabs/Lib/Chatroom.php +++ b/Zotlabs/Lib/Chatroom.php @@ -2,22 +2,18 @@ namespace Zotlabs\Lib; /** - * @brief Chat related functions. + * @brief A class with chatroom related static methods. */ - - - class Chatroom { /** * @brief Creates a chatroom. * * @param array $channel * @param array $arr - * @return An associative array containing: - * - success: A boolean - * - message: (optional) A string + * @return array An associative array containing: + * * \e boolean \b success - A boolean success status + * * \e string \b message - (optional) A string */ - static public function create($channel, $arr) { $ret = array('success' => false); @@ -150,8 +146,8 @@ class Chatroom { } if(intval($x[0]['cr_expire'])) { - $r = q("delete from chat where created < %s - INTERVAL %s and chat_room = %d", - db_utcnow(), + $r = q("delete from chat where created < %s - INTERVAL %s and chat_room = %d", + db_utcnow(), db_quoteinterval( intval($x[0]['cr_expire']) . ' MINUTE' ), intval($x[0]['cr_id']) ); @@ -225,10 +221,16 @@ class Chatroom { } /** - * create a chat message via API. + * @brief Create a chat message via API. + * * It is the caller's responsibility to enter the room. - */ - + * + * @param int $uid + * @param int $room_id + * @param string $xchan + * @param string $text + * @return array + */ static public function message($uid, $room_id, $xchan, $text) { $ret = array('success' => false); @@ -245,12 +247,18 @@ class Chatroom { if(! $r) return $ret; - $arr = array( + $arr = [ 'chat_room' => $room_id, 'chat_xchan' => $xchan, 'chat_text' => $text - ); - + ]; + /** + * @hooks chat_message + * Called to create a chat message. + * * \e int \b chat_room + * * \e string \b chat_xchan + * * \e string \b chat_text + */ call_hooks('chat_message', $arr); $x = q("insert into chat ( chat_room, chat_xchan, created, chat_text ) diff --git a/Zotlabs/Lib/Config.php b/Zotlabs/Lib/Config.php index 6e042feba..f9f22ba3a 100644 --- a/Zotlabs/Lib/Config.php +++ b/Zotlabs/Lib/Config.php @@ -1,4 +1,4 @@ -PConfig is used for channel specific configurations and takes a + * channel_id as identifier. It stores for example which features are + * enabled per channel. The storage is of size MEDIUMTEXT. + * + * @code{.php}$var = Zotlabs\Lib\PConfig::Get('uid', 'category', 'key'); + * // with default value for non existent key + * $var = Zotlabs\Lib\PConfig::Get('uid', 'category', 'unsetkey', 'defaultvalue');@endcode + * + * The old (deprecated?) way to access a PConfig value is: + * @code{.php}$var = get_pconfig(local_channel(), 'category', 'key');@endcode + */ class PConfig { /** @@ -13,9 +26,8 @@ class PConfig { * * @param string $uid * The channel_id - * @return void|false Nothing or false if $uid is false + * @return void|false Nothing or false if $uid is null or false */ - static public function Load($uid) { if(is_null($uid) || $uid === false) return false; @@ -64,11 +76,11 @@ class PConfig { * The category of the configuration value * @param string $key * The configuration key to query - * @param boolean $instore (deprecated, without function) + * @param mixed $default (optional, default false) + * Default value to return if key does not exist * @return mixed Stored value or false if it does not exist */ - - static public function Get($uid,$family,$key,$default = false) { + static public function Get($uid, $family, $key, $default = false) { if(is_null($uid) || $uid === false) return $default; @@ -79,11 +91,10 @@ class PConfig { if((! array_key_exists($family, \App::$config[$uid])) || (! array_key_exists($key, \App::$config[$uid][$family]))) return $default; - return ((! is_array(\App::$config[$uid][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$uid][$family][$key])) + return ((! is_array(\App::$config[$uid][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$uid][$family][$key])) ? unserialize(\App::$config[$uid][$family][$key]) : \App::$config[$uid][$family][$key] ); - } /** @@ -102,12 +113,11 @@ class PConfig { * The value to store * @return mixed Stored $value or false */ - static public function Set($uid, $family, $key, $value) { - // this catches subtle errors where this function has been called + // this catches subtle errors where this function has been called // with local_channel() when not logged in (which returns false) - // and throws an error in array_key_exists below. + // and throws an error in array_key_exists below. // we provide a function backtrace in the logs so that we can find // and fix the calling function. @@ -132,7 +142,6 @@ class PConfig { dbesc($key), dbesc($dbvalue) ); - } else { @@ -142,7 +151,6 @@ class PConfig { dbesc($family), dbesc($key) ); - } // keep a separate copy for all variables which were @@ -178,7 +186,6 @@ class PConfig { * The configuration key to delete * @return mixed */ - static public function Delete($uid, $family, $key) { if(is_null($uid) || $uid === false) @@ -186,12 +193,12 @@ class PConfig { $ret = false; - if(array_key_exists($uid,\App::$config) - && is_array(\App::$config['uid']) - && array_key_exists($family,\App::$config['uid']) + if(array_key_exists($uid,\App::$config) + && is_array(\App::$config['uid']) + && array_key_exists($family,\App::$config['uid']) && array_key_exists($key, \App::$config[$uid][$family])) unset(\App::$config[$uid][$family][$key]); - + $ret = q("DELETE FROM pconfig WHERE uid = %d AND cat = '%s' AND k = '%s'", intval($uid), dbesc($family), @@ -202,4 +209,3 @@ class PConfig { } } - \ No newline at end of file diff --git a/Zotlabs/Lib/SConfig.php b/Zotlabs/Lib/SConfig.php index ca0d133b2..ab6f49025 100644 --- a/Zotlabs/Lib/SConfig.php +++ b/Zotlabs/Lib/SConfig.php @@ -2,8 +2,11 @@ namespace Zotlabs\Lib; -// account configuration storage is built on top of the under-utilised xconfig - +/** + * @brief Account configuration storage is built on top of the under-utilised xconfig. + * + * @see XConfig + */ class SConfig { static public function Load($server_id) { diff --git a/Zotlabs/Lib/XConfig.php b/Zotlabs/Lib/XConfig.php index bf78c360f..c5a108ac9 100644 --- a/Zotlabs/Lib/XConfig.php +++ b/Zotlabs/Lib/XConfig.php @@ -2,7 +2,26 @@ namespace Zotlabs\Lib; - +/** + * @brief Class for handling observer's config. + * + * XConfig is comparable to PConfig, except that it uses xchan + * (an observer hash) as an identifier. + * + * XConfig is used for observer specific configurations and takes a + * xchan as identifier. + * The storage is of size MEDIUMTEXT. + * + * @code{.php}$var = Zotlabs\Lib\XConfig::Get('xchan', 'category', 'key'); + * // with default value for non existent key + * $var = Zotlabs\Lib\XConfig::Get('xchan', 'category', 'unsetkey', 'defaultvalue');@endcode + * + * The old (deprecated?) way to access a XConfig value is: + * @code{.php}$observer = App::get_observer_hash(); + * if ($observer) { + * $var = get_xconfig($observer, 'category', 'key'); + * }@endcode + */ class XConfig { /** @@ -15,7 +34,6 @@ class XConfig { * The observer's hash * @return void|false Returns false if xchan is not set */ - static public function Load($xchan) { if(! $xchan) @@ -56,9 +74,9 @@ class XConfig { * The category of the configuration value * @param string $key * The configuration key to query + * @param boolean $default (optional) default false * @return mixed Stored $value or false if it does not exist */ - static public function Get($xchan, $family, $key, $default = false) { if(! $xchan) @@ -70,7 +88,7 @@ class XConfig { if((! array_key_exists($family, \App::$config[$xchan])) || (! array_key_exists($key, \App::$config[$xchan][$family]))) return $default; - return ((! is_array(\App::$config[$xchan][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$xchan][$family][$key])) + return ((! is_array(\App::$config[$xchan][$family][$key])) && (preg_match('|^a:[0-9]+:{.*}$|s', \App::$config[$xchan][$family][$key])) ? unserialize(\App::$config[$xchan][$family][$key]) : \App::$config[$xchan][$family][$key] ); @@ -82,7 +100,6 @@ class XConfig { * Stores a config value ($value) in the category ($family) under the key ($key) * for the observer's $xchan hash. * - * * @param string $xchan * The observer's hash * @param string $family @@ -93,7 +110,6 @@ class XConfig { * The value to store * @return mixed Stored $value or false */ - static public function Set($xchan, $family, $key, $value) { // manage array value @@ -106,7 +122,7 @@ class XConfig { if(! array_key_exists($family, \App::$config[$xchan])) \App::$config[$xchan][$family] = array(); - $ret = q("INSERT INTO xconfig ( xchan, cat, k, v ) VALUES ( '%s', '%s', '%s', '%s' ) ", + $ret = q("INSERT INTO xconfig ( xchan, cat, k, v ) VALUES ( '%s', '%s', '%s', '%s' )", dbesc($xchan), dbesc($family), dbesc($key), @@ -126,6 +142,7 @@ class XConfig { if($ret) return $value; + return $ret; } @@ -143,11 +160,11 @@ class XConfig { * The configuration key to delete * @return mixed */ - static public function Delete($xchan, $family, $key) { if(x(\App::$config[$xchan][$family], $key)) unset(\App::$config[$xchan][$family][$key]); + $ret = q("DELETE FROM xconfig WHERE xchan = '%s' AND cat = '%s' AND k = '%s'", dbesc($xchan), dbesc($family), -- cgit v1.2.3