Commit 1a737be2 authored by Klaus Weidenbach's avatar Klaus Weidenbach

💡 Improving Doxygen documentation.

Fix some Doxygen parsing errors.
Improve hooks documentation.
parent 0ce7358f
<?php
namespace Zotlabs\Access;
use Zotlabs\Lib as Zlib;
/**
* @brief PermissionRoles class.
*
* @see Permissions
*/
class PermissionRoles {
/**
* @brief PermissionRoles version.
*
* This must match the version in Permissions.php before permission updates can run.
*
* @return number
*/
static public function version() {
return 2;
}
......@@ -23,12 +32,13 @@ class PermissionRoles {
$ret['default_collection'] = false;
$ret['directory_publish'] = true;
$ret['online'] = true;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'chat', 'post_like', 'republish' ];
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'chat', 'post_like', 'republish'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
case 'social_restricted':
......@@ -36,11 +46,11 @@ class PermissionRoles {
$ret['default_collection'] = true;
$ret['directory_publish'] = true;
$ret['online'] = true;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'chat', 'post_like' ];
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'chat', 'post_like'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
......@@ -50,10 +60,11 @@ class PermissionRoles {
$ret['default_collection'] = true;
$ret['directory_publish'] = false;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like' ];
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like'
];
$ret['limits'] = PermissionLimits::Std_Limits();
$ret['limits']['view_contacts'] = PERMS_SPECIFIC;
$ret['limits']['view_storage'] = PERMS_SPECIFIC;
......@@ -65,12 +76,13 @@ class PermissionRoles {
$ret['default_collection'] = false;
$ret['directory_publish'] = true;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'post_wall', 'post_comments', 'tag_deliver',
'post_mail', 'post_like' , 'republish', 'chat' ];
'post_mail', 'post_like' , 'republish', 'chat'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
case 'forum_restricted':
......@@ -78,11 +90,10 @@ class PermissionRoles {
$ret['default_collection'] = true;
$ret['directory_publish'] = true;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'post_wall', 'post_comments', 'tag_deliver',
'post_mail', 'post_like' , 'chat' ];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
......@@ -92,12 +103,11 @@ class PermissionRoles {
$ret['default_collection'] = true;
$ret['directory_publish'] = false;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'post_wall', 'post_comments',
'post_mail', 'post_like' , 'chat' ];
'post_mail', 'post_like' , 'chat'
];
$ret['limits'] = PermissionLimits::Std_Limits();
$ret['limits']['view_profile'] = PERMS_SPECIFIC;
$ret['limits']['view_contacts'] = PERMS_SPECIFIC;
......@@ -112,12 +122,11 @@ class PermissionRoles {
$ret['default_collection'] = false;
$ret['directory_publish'] = true;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like' , 'republish' ];
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like' , 'republish'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
......@@ -127,11 +136,11 @@ class PermissionRoles {
$ret['default_collection'] = true;
$ret['directory_publish'] = false;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like' , 'republish' ];
'view_pages', 'view_wiki', 'send_stream', 'post_wall', 'post_comments',
'post_mail', 'post_like' , 'republish'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
......@@ -141,11 +150,10 @@ class PermissionRoles {
$ret['default_collection'] = false;
$ret['directory_publish'] = true;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'post_like' , 'republish' ];
'view_pages', 'view_wiki', 'post_like' , 'republish'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
......@@ -155,13 +163,13 @@ class PermissionRoles {
$ret['default_collection'] = false;
$ret['directory_publish'] = true;
$ret['online'] = false;
$ret['perms_connect'] = [
$ret['perms_connect'] = [
'view_stream', 'view_profile', 'view_contacts', 'view_storage',
'view_pages', 'view_wiki', 'write_storage', 'write_pages', 'post_wall', 'post_comments', 'tag_deliver',
'post_mail', 'post_like' , 'republish', 'chat', 'write_wiki' ];
'post_mail', 'post_like' , 'republish', 'chat', 'write_wiki'
];
$ret['limits'] = PermissionLimits::Std_Limits();
break;
case 'custom':
......@@ -170,11 +178,15 @@ class PermissionRoles {
}
$x = get_config('system','role_perms');
// let system settings over-ride any or all
// let system settings over-ride any or all
if($x && is_array($x) && array_key_exists($role,$x))
$ret = array_merge($ret,$x[$role]);
call_hooks('get_role_perms',$ret);
/**
* @hooks get_role_perms
* * \e array
*/
call_hooks('get_role_perms', $ret);
return $ret;
}
......@@ -187,10 +199,10 @@ class PermissionRoles {
// \Zotlabs\Access\PermissionLimits::Set($uid,$perm,1);
if($perm === 'view_wiki')
\Zotlabs\Access\PermissionLimits::Set($uid,$perm,PERMS_PUBLIC);
\Zotlabs\Access\PermissionLimits::Set($uid, $perm, PERMS_PUBLIC);
if($perm === 'write_wiki')
\Zotlabs\Access\PermissionLimits::Set($uid,$perm,PERMS_SPECIFIC);
\Zotlabs\Access\PermissionLimits::Set($uid, $perm, PERMS_SPECIFIC);
// set autoperms here if applicable
......@@ -213,8 +225,6 @@ class PermissionRoles {
if($c) {
set_abconfig($uid,$c['channel_hash'],'autoperms',$perm,$value);
}
}
// now set something for all existing connections.
......@@ -242,38 +252,44 @@ class PermissionRoles {
}
}
/**
* @brief Array with translated role names and grouping.
*
* Return an associative array with grouped role names that can be used
* to create select groups like in \e field_select_grouped.tpl.
*
* @return array
*/
static public function roles() {
$roles = [
$roles = [
t('Social Networking') => [
'social' => t('Social - Mostly Public'),
'social_restricted' => t('Social - Restricted'),
'social' => t('Social - Mostly Public'),
'social_restricted' => t('Social - Restricted'),
'social_private' => t('Social - Private')
],
t('Community Forum') => [
'forum' => t('Forum - Mostly Public'),
'forum_restricted' => t('Forum - Restricted'),
'forum' => t('Forum - Mostly Public'),
'forum_restricted' => t('Forum - Restricted'),
'forum_private' => t('Forum - Private')
],
t('Feed Republish') => [
'feed' => t('Feed - Mostly Public'),
'feed' => t('Feed - Mostly Public'),
'feed_restricted' => t('Feed - Restricted')
],
t('Special Purpose') => [
'soapbox' => t('Special - Celebrity/Soapbox'),
'soapbox' => t('Special - Celebrity/Soapbox'),
'repository' => t('Special - Group Repository')
],
t('Other') => [
'custom' => t('Custom/Expert Mode')
]
];
return $roles;
return $roles;
}
}
\ No newline at end of file
......@@ -33,19 +33,22 @@ use Zotlabs\Lib as Zlib;
*/
class Permissions {
/**
* @brief Permissions version.
*
* This must match the version in PermissionRoles.php before permission updates can run.
*
* @return number
*/
static public function version() {
// This must match the version in PermissionRoles.php before permission updates can run.
return 2;
}
/**
* @brief Return an array with Permissions.
*
* @hooks permissions_list
* * \e array \b permissions
* * \e string \b filter
* @param string $filter (optional) only passed to hook permission_list
* @return Associative array with permissions and short description.
* @param string $filter (optional) only passed to hook permissions_list
* @return array Associative array with permissions and short description.
*/
static public function Perms($filter = '') {
......@@ -74,6 +77,11 @@ class Permissions {
'permissions' => $perms,
'filter' => $filter
];
/**
* @hooks permissions_list
* * \e array \b permissions
* * \e string \b filter
*/
call_hooks('permissions_list', $x);
return($x['permissions']);
......@@ -84,9 +92,7 @@ class Permissions {
*
* e.g. you must be authenticated.
*
* @hooks write_perms
* * \e array \b permissions
* @return Associative array with permissions and short description.
* @return array Associative array with permissions and short description.
*/
static public function BlockedAnonPerms() {
......@@ -99,6 +105,10 @@ class Permissions {
}
$x = ['permissions' => $res];
/**
* @hooks write_perms
* * \e array \b permissions
*/
call_hooks('write_perms', $x);
return($x['permissions']);
......@@ -138,7 +148,7 @@ class Permissions {
* to [ 0 => ['name' => 'view_stream', 'value' => 1], ... ]
*
* @param array $arr associative perms array 'view_stream' => 1
* @return Indexed array with elements that look like
* @return array Indexed array with elements that look like
* * \e string \b name the perm name (e.g. view_stream)
* * \e int \b value the value of the perm (e.g. 1)
*/
......@@ -197,11 +207,10 @@ class Permissions {
* @brief
*
* @param int $channel_id A channel id
* @return associative array
* @return array Associative array with
* * \e array \b perms Permission array
* * \e int \b automatic 0 or 1
*/
static public function connect_perms($channel_id) {
$my_perms = [];
......
......@@ -2,7 +2,12 @@
namespace Zotlabs\Extend;
use App;
/**
* @brief Hook class.
*
*/
class Hook {
static public function register($hook,$file,$function,$version = 1,$priority = 0) {
......@@ -64,11 +69,14 @@ class Hook {
return $r;
}
// unregister all hooks with this file component.
// Useful for addon upgrades where you want to clean out old interfaces.
/**
* @brief Unregister all hooks with this file component.
*
* Useful for addon upgrades where you want to clean out old interfaces.
*
* @param string $file
*/
static public function unregister_by_file($file) {
$r = q("DELETE FROM hook WHERE file = '%s' ",
dbesc($file)
);
......@@ -76,7 +84,6 @@ class Hook {
return $r;
}
/**
* @brief Inserts a hook into a page request.
*
......@@ -98,7 +105,6 @@ class Hook {
* @param int $priority
* currently not implemented in this function, would require the hook array to be resorted
*/
static public function insert($hook, $fn, $version = 0, $priority = 0) {
if(is_array($fn)) {
$fn = serialize($fn);
......
......@@ -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;
}
......
......@@ -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 )
......
<?php /** @file */
<?php
namespace Zotlabs\Lib;
......@@ -14,7 +14,6 @@ class Config {
* @param string $family
* The category of the configuration value
*/
static public function Load($family) {
if(! array_key_exists($family, \App::$config))
\App::$config[$family] = array();
......@@ -30,7 +29,7 @@ class Config {
}
\App::$config[$family]['config_loaded'] = true;
}
}
}
}
/**
......@@ -47,8 +46,7 @@ class Config {
* @return mixed
* Return the set value, or false if the database update failed
*/
static public function Set($family,$key,$value) {
static public function Set($family, $key, $value) {
// manage array value
$dbvalue = ((is_array($value)) ? serialize($value) : $value);
$dbvalue = ((is_bool($dbvalue)) ? intval