harukin/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct and extend Doxygen comments.

Browse Source 
Correct some documentation errors for Doxygen and add
more comments.
Document some undefined variables with @FIXME.
This commit is contained in:
Klaus Weidenbach 2019-01-18 22:17:10 +01:00
parent 51a7be29f5
commit 13e0151cd2
12 changed files with 351 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
Zotlabs/Lib/Libzot.php
View File

@ -2,11 +2,6 @@
namespace Zotlabs\Lib; namespace Zotlabs\Lib;
/**
* @brief lowlevel implementation of Zot6 protocol.
*
*/
use Zotlabs\Zot6\HTTPSig; use Zotlabs\Zot6\HTTPSig;
use Zotlabs\Access\Permissions; use Zotlabs\Access\Permissions;
use Zotlabs\Access\PermissionLimits; use Zotlabs\Access\PermissionLimits;
@ -14,14 +9,17 @@ use Zotlabs\Daemon\Master;
require_once('include/crypto.php'); require_once('include/crypto.php');
/**
* @brief Lowlevel implementation of Zot6 protocol.
*
*/
class Libzot { class Libzot {
/** /**
* @brief Generates a unique string for use as a zot guid. * @brief Generates a unique string for use as a zot guid.
* *
* Generates a unique string for use as a zot guid using our DNS-based url, the * Generates a unique string for use as a zot guid using our DNS-based url,
* channel nickname and some entropy. * the channel nickname and some entropy.
* The entropy ensures uniqueness against re-installs where the same URL and * The entropy ensures uniqueness against re-installs where the same URL and
* nickname are chosen. * nickname are chosen.
* *
@ -32,9 +30,8 @@ class Libzot {
* immediate universe. * immediate universe.
* *
* @param string $channel_nick a unique nickname of controlling entity * @param string $channel_nick a unique nickname of controlling entity
* @returns string * @return string
*/ */
static function new_uid($channel_nick) { static function new_uid($channel_nick) {
$rawstr = z_root() . '/' . $channel_nick . '.' . mt_rand(); $rawstr = z_root() . '/' . $channel_nick . '.' . mt_rand();
return(base64url_encode(hash('whirlpool', $rawstr, true), true)); return(base64url_encode(hash('whirlpool', $rawstr, true), true));
@ -52,8 +49,8 @@ class Libzot {
* *
* @param string $guid * @param string $guid
* @param string $pubkey * @param string $pubkey
* @return string
*/ */
static function make_xchan_hash($guid, $pubkey) { static function make_xchan_hash($guid, $pubkey) {
return base64url_encode(hash('whirlpool', $guid . $pubkey, true)); return base64url_encode(hash('whirlpool', $guid . $pubkey, true));
} }
@ -65,10 +62,8 @@ class Libzot {
* should only be used by channels which are defined on this hub. * should only be used by channels which are defined on this hub.
* *
* @param string $hash - xchan_hash * @param string $hash - xchan_hash
* @returns array of hubloc (hub location structures) * @return array of hubloc (hub location structures)
*
*/ */
static function get_hublocs($hash) { static function get_hublocs($hash) {
/* Only search for active hublocs - e.g. those that haven't been marked deleted */ /* Only search for active hublocs - e.g. those that haven't been marked deleted */
@ -92,16 +87,17 @@ class Libzot {
* packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'keychange', 'force_refresh', 'notify', 'auth_check' * packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'keychange', 'force_refresh', 'notify', 'auth_check'
* @param array $recipients * @param array $recipients
* envelope recipients, array of portable_id's; empty for public posts * envelope recipients, array of portable_id's; empty for public posts
* @param string msg * @param string $msg
* optional message * optional message
* @param string $encoding
* optional encoding, default 'activitystreams'
* @param string $remote_key * @param string $remote_key
* optional public site key of target hub used to encrypt entire packet * optional public site key of target hub used to encrypt entire packet
* NOTE: remote_key and encrypted packets are required for 'auth_check' packets, optional for all others * NOTE: remote_key and encrypted packets are required for 'auth_check' packets, optional for all others
* @param string $methods * @param string $methods
* optional comma separated list of encryption methods @ref self::best_algorithm() * optional comma separated list of encryption methods @ref best_algorithm()
* @returns string json encoded zot packet * @returns string json encoded zot packet
*/ */
static function build_packet($channel, $type = 'activity', $recipients = null, $msg = '', $encoding = 'activitystreams', $remote_key = null, $methods = '') { static function build_packet($channel, $type = 'activity', $recipients = null, $msg = '', $encoding = 'activitystreams', $remote_key = null, $methods = '') {
$sig_method = get_config('system','signature_algorithm','sha256'); $sig_method = get_config('system','signature_algorithm','sha256');
@ -146,11 +142,10 @@ class Libzot {
* @brief Choose best encryption function from those available on both sites. * @brief Choose best encryption function from those available on both sites.
* *
* @param string $methods * @param string $methods
* comma separated list of encryption methods * Comma separated list of encryption methods
* @return string first match from our site method preferences crypto_methods() array * @return string first match from our site method preferences crypto_methods() array
* of a method which is common to both sites; or 'aes256cbc' if no matches are found. * of a method which is common to both sites; or 'aes256cbc' if no matches are found.
*/ */
static function best_algorithm($methods) { static function best_algorithm($methods) {
$x = [ $x = [
@ -164,7 +159,6 @@ class Libzot {
* * \e string \b methods - comma separated list of encryption methods * * \e string \b methods - comma separated list of encryption methods
* * \e string \b result - the algorithm to return * * \e string \b result - the algorithm to return
*/ */
call_hooks('zot_best_algorithm', $x); call_hooks('zot_best_algorithm', $x);
if($x['result']) if($x['result'])
@ -190,7 +184,7 @@ class Libzot {
/** /**
* @brief send a zot message * @brief Send a zot message.
* *
* @see z_post_url() * @see z_post_url()
* *
@ -200,7 +194,6 @@ class Libzot {
* @param array $crypto (required if encrypted httpsig, requires hubloc_sitekey and site_crypto elements) * @param array $crypto (required if encrypted httpsig, requires hubloc_sitekey and site_crypto elements)
* @return array see z_post_url() for returned data format * @return array see z_post_url() for returned data format
*/ */
static function zot($url, $data, $channel = null,$crypto = null) { static function zot($url, $data, $channel = null,$crypto = null) {
if($channel) { if($channel) {
@ -227,7 +220,6 @@ class Libzot {
/** /**
* @brief Refreshes after permission changed or friending, etc. * @brief Refreshes after permission changed or friending, etc.
* *
*
* refresh is typically invoked when somebody has changed permissions of a channel and they are notified * refresh is typically invoked when somebody has changed permissions of a channel and they are notified
* to fetch new permissions via a finger/discovery operation. This may result in a new connection * to fetch new permissions via a finger/discovery operation. This may result in a new connection
* (abook entry) being added to a local channel and it may result in auto-permissions being granted. * (abook entry) being added to a local channel and it may result in auto-permissions being granted.
@ -251,7 +243,6 @@ class Libzot {
* * \b true if successful * * \b true if successful
* * otherwise \b false * * otherwise \b false
*/ */
static function refresh($them, $channel = null, $force = false) { static function refresh($them, $channel = null, $force = false) {
logger('them: ' . print_r($them,true), LOGGER_DATA, LOG_DEBUG); logger('them: ' . print_r($them,true), LOGGER_DATA, LOG_DEBUG);
@ -317,6 +308,7 @@ class Libzot {
if(! $hsig_valid) { if(! $hsig_valid) {
logger('http signature not valid: ' . print_r($hsig,true)); logger('http signature not valid: ' . print_r($hsig,true));
/// @FIXME $result is undefined
return $result; return $result;
} }
@ -524,9 +516,13 @@ class Libzot {
return false; return false;
} }
/**
* @brief
*
* @param string $sender
* @param string $site_id
* @return null|array
*/
static function valid_hub($sender, $site_id) { static function valid_hub($sender, $site_id) {
$r = q("select hubloc.*, site.site_crypto from hubloc left join site on hubloc_url = site_url where hubloc_hash = '%s' and hubloc_site_id = '%s' limit 1", $r = q("select hubloc.*, site.site_crypto from hubloc left join site on hubloc_url = site_url where hubloc_hash = '%s' and hubloc_site_id = '%s' limit 1",
@ -548,7 +544,6 @@ class Libzot {
} }
return $r[0]; return $r[0];
} }
/** /**
@ -559,21 +554,14 @@ class Libzot {
* origination address. This will fetch the discovery packet of the sender, * origination address. This will fetch the discovery packet of the sender,
* which contains the public key we need to verify our guid and url signatures. * which contains the public key we need to verify our guid and url signatures.
* *
* @param array $arr an associative array which must contain: * @param string $id
* * \e string \b guid => guid of conversant
* * \e string \b guid_sig => guid signed with conversant's private key
* * \e string \b url => URL of the origination hub of this communication
* * \e string \b url_sig => URL signed with conversant's private key
* *
* @return array An associative array with * @return array An associative array with
* * \b success boolean true or false * * \e boolean \b success
* * \b message (optional) error string only if success is false * * \e string \b message (optional, unused) error string only if success is false
*/ */
static function register_hub($id) { static function register_hub($id) {
$id_hash = false;
$valid = false;
$hsig_valid = false; $hsig_valid = false;
$result = [ 'success' => false ]; $result = [ 'success' => false ];
@ -954,8 +942,8 @@ class Libzot {
* @param string $hub - url of site we just contacted * @param string $hub - url of site we just contacted
* @param array $arr - output of z_post_url() * @param array $arr - output of z_post_url()
* @param array $outq - The queue structure attached to this request * @param array $outq - The queue structure attached to this request
* @return void
*/ */
static function process_response($hub, $arr, $outq) { static function process_response($hub, $arr, $outq) {
logger('remote: ' . print_r($arr,true),LOGGER_DATA); logger('remote: ' . print_r($arr,true),LOGGER_DATA);
@ -1083,11 +1071,6 @@ class Libzot {
* *
* @param array $arr * @param array $arr
* 'pickup' structure returned from remote site * 'pickup' structure returned from remote site
* @param string $sender_url
* the url specified by the sender in the initial communication.
* We will verify the sender and url in each returned message structure and
* also verify that all the messages returned match the site url that we are
* currently processing.
* *
* @returns array * @returns array
* Suitable for logging remotely, enumerating the processing results of each message/recipient combination * Suitable for logging remotely, enumerating the processing results of each message/recipient combination
@ -1095,7 +1078,6 @@ class Libzot {
* * [1] => \e string $delivery_status * * [1] => \e string $delivery_status
* * [2] => \e string $address * * [2] => \e string $address
*/ */
static function import($arr) { static function import($arr) {
$env = $arr; $env = $arr;
@ -1175,7 +1157,6 @@ class Libzot {
$deliveries = self::public_recips($env,$AS); $deliveries = self::public_recips($env,$AS);
} }
$deliveries = array_unique($deliveries); $deliveries = array_unique($deliveries);
@ -1218,7 +1199,7 @@ class Libzot {
if($private) { if($private) {
$arr['item_private'] = true; $arr['item_private'] = true;
} }
// @fixme - spoofable /// @FIXME - spoofable
if($AS->data['hubloc']) { if($AS->data['hubloc']) {
$arr['item_verified'] = true; $arr['item_verified'] = true;
} }
@ -1252,6 +1233,13 @@ class Libzot {
} }
/**
* @brief
*
* @param array $env
* @param object $act
* @return boolean
*/
static function is_top_level($env, $act) { static function is_top_level($env, $act) {
if($env['encoding'] === 'zot' && array_key_exists('flags',$env) && in_array('thread_parent', $env['flags'])) { if($env['encoding'] === 'zot' && array_key_exists('flags',$env) && in_array('thread_parent', $env['flags'])) {
return true; return true;
@ -1295,9 +1283,9 @@ class Libzot {
* Some of these will be rejected, but this gives us a place to start. * Some of these will be rejected, but this gives us a place to start.
* *
* @param array $msg * @param array $msg
* @return NULL|array * @param object $act
* @return array
*/ */
static function public_recips($msg, $act) { static function public_recips($msg, $act) {
require_once('include/channel.php'); require_once('include/channel.php');
@ -1822,7 +1810,7 @@ class Libzot {
$arr['owner_xchan'] = $a['signature']['signer']; $arr['owner_xchan'] = $a['signature']['signer'];
} }
// @fixme - spoofable /// @FIXME - spoofable
if($AS->data['hubloc']) { if($AS->data['hubloc']) {
$arr['item_verified'] = true; $arr['item_verified'] = true;
} }
@ -1853,8 +1841,8 @@ class Libzot {
* * \e int \b obj_type * * \e int \b obj_type
* * \e int \b mid * * \e int \b mid
* @param int $uid * @param int $uid
* @return void
*/ */
static function remove_community_tag($sender, $arr, $uid) { static function remove_community_tag($sender, $arr, $uid) {
if(! (activity_match($arr['verb'], ACTIVITY_TAG) && ($arr['obj_type'] == ACTIVITY_OBJ_TAGTERM))) if(! (activity_match($arr['verb'], ACTIVITY_TAG) && ($arr['obj_type'] == ACTIVITY_OBJ_TAGTERM)))
@ -1925,8 +1913,8 @@ class Libzot {
* @param array $orig * @param array $orig
* @param int $uid * @param int $uid
* @param boolean $tag_delivery * @param boolean $tag_delivery
* @return void|array
*/ */
static function update_imported_item($sender, $item, $orig, $uid, $tag_delivery) { static function update_imported_item($sender, $item, $orig, $uid, $tag_delivery) {
// If this is a comment being updated, remove any privacy information // If this is a comment being updated, remove any privacy information
@ -2145,12 +2133,13 @@ class Libzot {
* @brief Processes delivery of profile. * @brief Processes delivery of profile.
* *
* @see import_directory_profile() * @see import_directory_profile()
*
* @param array $sender an associative array * @param array $sender an associative array
* * \e string \b hash a xchan_hash * * \e string \b hash a xchan_hash
* @param array $arr * @param array $arr
* @param array $deliveries (unused) * @param array $deliveries (unused)
* @return void
*/ */
static function process_profile_delivery($sender, $arr, $deliveries) { static function process_profile_delivery($sender, $arr, $deliveries) {
logger('process_profile_delivery', LOGGER_DEBUG); logger('process_profile_delivery', LOGGER_DEBUG);
@ -2171,6 +2160,7 @@ class Libzot {
* * \e string \b hash a xchan_hash * * \e string \b hash a xchan_hash
* @param array $arr * @param array $arr
* @param array $deliveries (unused) deliveries is irrelevant * @param array $deliveries (unused) deliveries is irrelevant
* @return void
*/ */
static function process_location_delivery($sender, $arr, $deliveries) { static function process_location_delivery($sender, $arr, $deliveries) {
@ -2188,7 +2178,7 @@ class Libzot {
$x = Libsync::sync_locations($xchan,$arr,true); $x = Libsync::sync_locations($xchan,$arr,true);
logger('results: ' . print_r($x,true), LOGGER_DEBUG); logger('results: ' . print_r($x,true), LOGGER_DEBUG);
if($x['changed']) { if($x['changed']) {
$guid = random_string() . '@' . App::get_hostname(); //$guid = random_string() . '@' . App::get_hostname();
Libzotdir::update_modtime($sender,$r[0]['xchan_guid'],$arr['locations'][0]['address'],UPDATE_FLAGS_UPDATED); Libzotdir::update_modtime($sender,$r[0]['xchan_guid'],$arr['locations'][0]['address'],UPDATE_FLAGS_UPDATED);
} }
} }
@ -2212,8 +2202,8 @@ class Libzot {
* *
* @param string $sender_hash A channel hash * @param string $sender_hash A channel hash
* @param array $locations * @param array $locations
* @return void
*/ */
static function check_location_move($sender_hash, $locations) { static function check_location_move($sender_hash, $locations) {
if(! $locations) if(! $locations)
@ -2255,7 +2245,6 @@ class Libzot {
} }
/** /**
* @brief Returns an array with all known distinct hubs for this channel. * @brief Returns an array with all known distinct hubs for this channel.
* *
@ -2264,7 +2253,6 @@ class Libzot {
* * \e string \b channel_hash the hash of the channel * * \e string \b channel_hash the hash of the channel
* @return array an array with associative arrays * @return array an array with associative arrays
*/ */
static function encode_locations($channel) { static function encode_locations($channel) {
$ret = []; $ret = [];
@ -2318,10 +2306,8 @@ class Libzot {
* @brief * @brief
* *
* @param array $arr * @param array $arr
* @param string $pubkey
* @return boolean true if updated or inserted * @return boolean true if updated or inserted
*/ */
static function import_site($arr) { static function import_site($arr) {
if( (! is_array($arr)) || (! $arr['url']) || (! $arr['site_sig'])) if( (! is_array($arr)) || (! $arr['url']) || (! $arr['site_sig']))
@ -2836,14 +2822,20 @@ class Libzot {
$ret['locations'] = $x; $ret['locations'] = $x;
$ret['site'] = self::site_info(); $ret['site'] = self::site_info();
/**
* @hooks zotinfo
* Hook to manipulate the zotinfo array before it is returned.
*/
call_hooks('zotinfo', $ret); call_hooks('zotinfo', $ret);
return($ret); return $ret;
} }
/**
* @brief Get siteinfo.
*
* @return array
*/
static function site_info() { static function site_info() {
$signing_key = get_config('system','prvkey'); $signing_key = get_config('system','prvkey');
@ -2927,18 +2919,16 @@ class Libzot {
} }
return $ret['site']; return $ret['site'];
} }
/** /**
* @brief * @brief
* *
* @param array $hub * @param array $hub
* @param string $sitekey (optional, default empty) * @param string $site_id (optional, default empty)
* *
* @return string hubloc_url * @return string hubloc_url
*/ */
static function update_hub_connected($hub, $site_id = '') { static function update_hub_connected($hub, $site_id = '') {
if ($site_id) { if ($site_id) {
@ -2997,12 +2987,21 @@ class Libzot {
return $hub['hubloc_url']; return $hub['hubloc_url'];
} }
/**
* @brief
*
* @param string $data
* @param string $key
* @param string $alg (optional) default 'sha256'
* @return string
*/
static function sign($data,$key,$alg = 'sha256') { static function sign($data,$key,$alg = 'sha256') {
if(! $key) if(! $key)
return 'no key'; return 'no key';
$sig = ''; $sig = '';
openssl_sign($data,$sig,$key,$alg); openssl_sign($data,$sig,$key,$alg);
return $alg . '.' . base64url_encode($sig); return $alg . '.' . base64url_encode($sig);
} }
@ -3028,11 +3027,14 @@ class Libzot {
return(($verify > 0) ? true : false); return(($verify > 0) ? true : false);
} }
/**
* @brief
*
* @return boolean
*/
static function is_zot_request() { static function is_zot_request() {
$x = getBestSupportedMimeType([ 'application/x-zot+json' ]); $x = getBestSupportedMimeType([ 'application/x-zot+json' ]);
return(($x) ? true : false); return(($x) ? true : false);
} }

7
Zotlabs/Lib/PConfig.php
View File

@ -112,6 +112,8 @@ class PConfig {
* The configuration key to set * The configuration key to set
* @param string $value * @param string $value
* The value to store * The value to store
* @param string $updated (optional)
* The datetime to store
* @return mixed Stored $value or false * @return mixed Stored $value or false
*/ */
static public function Set($uid, $family, $key, $value, $updated = NULL) { static public function Set($uid, $family, $key, $value, $updated = NULL) {
@ -239,7 +241,9 @@ class PConfig {
* The category of the configuration value * The category of the configuration value
* @param string $key * @param string $key
* The configuration key to delete * The configuration key to delete
* @return mixed * @param string $updated (optional)
* The datetime to store
* @return boolean
*/ */
static public function Delete($uid, $family, $key, $updated = NULL) { static public function Delete($uid, $family, $key, $updated = NULL) {
@ -283,6 +287,7 @@ class PConfig {
if(! array_key_exists($family, \App::$config[$uid]['transient'])) if(! array_key_exists($family, \App::$config[$uid]['transient']))
\App::$config[$uid]['transient'][$family] = array(); \App::$config[$uid]['transient'][$family] = array();
/// @FIXME $new is undefined, so dead code
if ($new) { if ($new) {
\App::$config[$uid]['transient'][$family]['pcfgdel:'.$key] = $updated; \App::$config[$uid]['transient'][$family]['pcfgdel:'.$key] = $updated;
} }

14
Zotlabs/Module/Cards.php
View File

@ -10,9 +10,13 @@ require_once('include/channel.php');
require_once('include/conversation.php'); require_once('include/conversation.php');
require_once('include/acl_selectors.php'); require_once('include/acl_selectors.php');
/**
* @brief Provides the Cards module.
*
*/
class Cards extends Controller { class Cards extends Controller {
function init() { public function init() {
if(argc() > 1) if(argc() > 1)
$which = argv(1); $which = argv(1);
@ -20,14 +24,15 @@ class Cards extends Controller {
return; return;
profile_load($which); profile_load($which);
} }
/** /**
* {@inheritDoc} * {@inheritDoc}
* @see \Zotlabs\Web\Controller::get() * @see \\Zotlabs\\Web\\Controller::get()
*
* @return string Parsed HTML from template 'cards.tpl'
*/ */
function get($update = 0, $load = false) { public function get($update = 0, $load = false) {
if(observer_prohibited(true)) { if(observer_prohibited(true)) {
return login(); return login();
@ -99,7 +104,6 @@ class Cards extends Controller {
} }
if(perm_is_allowed($owner, $ob_hash, 'write_pages')) { if(perm_is_allowed($owner, $ob_hash, 'write_pages')) {
$x = [ $x = [

24
Zotlabs/Zot6/Zot6Handler.php
View File

@ -58,10 +58,10 @@ class Zot6Handler implements IHandler {
* *
* @param array $sender * @param array $sender
* @param array $recipients * @param array $recipients
* @param array $hub
* *
* @return json_return_and_die() * @return array
*/ */
static function reply_refresh($sender, $recipients, $hub) { static function reply_refresh($sender, $recipients, $hub) {
$ret = array('success' => false); $ret = array('success' => false);
@ -70,19 +70,18 @@ class Zot6Handler implements IHandler {
// This would be a permissions update, typically for one connection // This would be a permissions update, typically for one connection
foreach ($recipients as $recip) { foreach ($recipients as $recip) {
$r = q("select channel.*,xchan.* from channel $r = q("select channel.*,xchan.* from channel
left join xchan on channel_portable_id = xchan_hash left join xchan on channel_portable_id = xchan_hash
where xchan_hash ='%s' limit 1", where xchan_hash ='%s' limit 1",
dbesc($recip) dbesc($recip)
); );
/// @FIXME $msgtype is undefined
$x = Libzot::refresh( [ 'hubloc_id_url' => $hub['hubloc_id_url'] ], $r[0], (($msgtype === 'force_refresh') ? true : false)); $x = Libzot::refresh( [ 'hubloc_id_url' => $hub['hubloc_id_url'] ], $r[0], (($msgtype === 'force_refresh') ? true : false));
} }
} }
else { else {
// system wide refresh // system wide refresh
/// @FIXME $msgtype is undefined
$x = Libzot::refresh( [ 'hubloc_id_url' => $hub['hubloc_id_url'] ], null, (($msgtype === 'force_refresh') ? true : false)); $x = Libzot::refresh( [ 'hubloc_id_url' => $hub['hubloc_id_url'] ], null, (($msgtype === 'force_refresh') ? true : false));
} }
@ -105,11 +104,10 @@ class Zot6Handler implements IHandler {
* this 'message_list' at the destination and split it into individual messages which are * this 'message_list' at the destination and split it into individual messages which are
* processed/delivered in order. * processed/delivered in order.
* *
*
* @param array $data * @param array $data
* @param array $hub
* @return array * @return array
*/ */
static function reply_message_request($data, $hub) { static function reply_message_request($data, $hub) {
$ret = [ 'success' => false ]; $ret = [ 'success' => false ];
@ -153,11 +151,10 @@ class Zot6Handler implements IHandler {
/* /*
* fetch the requested conversation * fetch the requested conversation
*/ */
/// @FIXME $sender_hash is undefined
$messages = zot_feed($c[0]['channel_id'],$sender_hash, [ 'message_id' => $data['message_id'], 'encoding' => 'activitystreams' ]); $messages = zot_feed($c[0]['channel_id'],$sender_hash, [ 'message_id' => $data['message_id'], 'encoding' => 'activitystreams' ]);
return (($messages) ? : [] ); return (($messages) ? : [] );
} }
static function rekey_request($sender,$data,$hub) { static function rekey_request($sender,$data,$hub) {
@ -219,10 +216,10 @@ class Zot6Handler implements IHandler {
* *
* @param array $sender * @param array $sender
* @param array $recipients * @param array $recipients
* @param array $hub
* *
* return json_return_and_die() * @return array
*/ */
static function reply_purge($sender, $recipients, $hub) { static function reply_purge($sender, $recipients, $hub) {
$ret = array('success' => false); $ret = array('success' => false);
@ -259,9 +256,4 @@ class Zot6Handler implements IHandler {
return $ret; return $ret;
} }
} }

44
include/attach.php
View File

@ -137,7 +137,7 @@ function z_mime_content_type($filename) {
* @param string $hash (optional) * @param string $hash (optional)
* @param string $filename (optional) * @param string $filename (optional)
* @param string $filetype (optional) * @param string $filetype (optional)
* @return associative array with: * @return array Associative array with:
* * \e boolean \b success * * \e boolean \b success
* * \e int|boolean \b results amount of found results, or false * * \e int|boolean \b results amount of found results, or false
* * \e string \b message with error messages if any * * \e string \b message with error messages if any
@ -176,15 +176,17 @@ function attach_count_files($channel_id, $observer, $hash = '', $filename = '',
/** /**
* @brief Returns a list of files/attachments. * @brief Returns a list of files/attachments.
* *
* @param $channel_id * @param int $channel_id
* @param $observer * @param string $observer
* @param $hash (optional) * @param string $hash (optional)
* @param $filename (optional) * @param string $filename (optional)
* @param $filetype (optional) * @param string $filetype (optional)
* @param $orderby * @param string $orderby (optional)
* @param $start * @param int $start (optional)
* @param $entries * @param int $entries (optional)
* @return associative array with: * @param string $since (optional)
* @param string $until (optional)
* @return array an associative array with:
* * \e boolean \b success * * \e boolean \b success
* * \e array|boolean \b results array with results, or false * * \e array|boolean \b results array with results, or false
* * \e string \b message with error messages if any * * \e string \b message with error messages if any
@ -1429,7 +1431,16 @@ function attach_delete($channel_id, $resource, $is_photo = 0) {
if(! $r) { if(! $r) {
attach_drop_photo($channel_id,$resource); attach_drop_photo($channel_id,$resource);
$arr = ['channel_id' => $channel_id, 'resource' => $resource, 'is_photo' => $is_photo]; $arr = ['channel_id' => $channel_id, 'resource' => $resource, 'is_photo' => $is_photo];
call_hooks("attach_delete",$arr);
/**
* @hooks attach_delete
* Called when deleting an attachment from channel.
* * \e int \b channel_id - the channel_id
* * \e string \b resource
* * \e int \b is_photo
*/
call_hooks('attach_delete', $arr);
return; return;
} }
@ -1489,7 +1500,14 @@ function attach_delete($channel_id, $resource, $is_photo = 0) {
); );
$arr = ['channel_id' => $channel_id, 'resource' => $resource, 'is_photo' => $is_photo]; $arr = ['channel_id' => $channel_id, 'resource' => $resource, 'is_photo' => $is_photo];
call_hooks("attach_delete",$arr); /**
* @hooks attach_delete
* Called when deleting an attachment from channel.
* * \e int \b channel_id - the channel_id
* * \e string \b resource
* * \e int \b is_photo
*/
call_hooks('attach_delete', $arr);
file_activity($channel_id, $object, $object['allow_cid'], $object['allow_gid'], $object['deny_cid'], $object['deny_gid'], 'update', true); file_activity($channel_id, $object, $object['allow_cid'], $object['allow_gid'], $object['deny_cid'], $object['deny_gid'], 'update', true);
@ -1868,7 +1886,7 @@ function file_activity($channel_id, $object, $allow_cid, $allow_gid, $deny_cid,
* @param int $channel_id * @param int $channel_id
* @param string $hash * @param string $hash
* @param string $url * @param string $url
* @return array An associative array for the specified file. * @return array Associative array for the specified file.
*/ */
function get_file_activity_object($channel_id, $hash, $url) { function get_file_activity_object($channel_id, $hash, $url) {

8
include/feedutils.php
View File

@ -261,13 +261,13 @@ function construct_activity_target($item) {
* @param SimplePie $item * @param SimplePie $item
* @return array $author * @return array $author
*/ */
function get_atom_author($feed, $item) { function get_atom_author($feed, $item) {
$author = []; $author = [];
$found_author = $item->get_author(); $found_author = $item->get_author();
if($found_author) { if($found_author) {
/// @FIXME $rawauthor is undefined here
if($rawauthor) { if($rawauthor) {
if($rawauthor[0]['child'][NAMESPACE_POCO]['displayName'][0]['data']) if($rawauthor[0]['child'][NAMESPACE_POCO]['displayName'][0]['data'])
$author['full_name'] = unxmlify($rawauthor[0]['child'][NAMESPACE_POCO]['displayName'][0]['data']); $author['full_name'] = unxmlify($rawauthor[0]['child'][NAMESPACE_POCO]['displayName'][0]['data']);
@ -398,10 +398,10 @@ function get_atom_author($feed, $item) {
'author' => $author 'author' => $author
]; ];
/** /**
* @hooks parse_atom * @hooks parse_atom_author
* * \e SimplePie \b feed - The original SimplePie feed * * \e SimplePie \b feed - The original SimplePie feed
* * \e SimplePie \b item * * \e SimplePie \b item
* * \e array \b result - the result array that will also get returned * * \e array \b author - the result array that will also get returned
*/ */
call_hooks('parse_atom_author', $arr); call_hooks('parse_atom_author', $arr);
@ -416,10 +416,8 @@ function get_atom_author($feed, $item) {
* *
* @param SimplePie $feed * @param SimplePie $feed
* @param SimplePie $item * @param SimplePie $item
* @param[out] array $author
* @return array Associative array with the parsed item data * @return array Associative array with the parsed item data
*/ */
function get_atom_elements($feed, $item) { function get_atom_elements($feed, $item) {
require_once('include/html2bbcode.php'); require_once('include/html2bbcode.php');

28
include/help.php
View File

@ -7,7 +7,8 @@ use \Michelf\MarkdownExtra;
* @brief * @brief
* *
* @param string $path * @param string $path
* @return string|unknown * @param string $suffix (optional) default null
* @return string
*/ */
function get_help_fullpath($path, $suffix = null) { function get_help_fullpath($path, $suffix = null) {
@ -49,8 +50,8 @@ function get_help_fullpath($path,$suffix=null) {
/** /**
* @brief * @brief
* *
* @param string $tocpath * @param string $tocpath (optional) default false
* @return string|unknown * @return string
*/ */
function get_help_content($tocpath = false) { function get_help_content($tocpath = false) {
@ -171,16 +172,20 @@ function preg_callback_help_include($matches) {
} }
/** /**
* @brief * @brief Determines help language.
* *
* @return boolean|array * If the language was specified in the URL, override the language preference
* of the browser. Default to English if both of these are absent.
*
* @return array Associative array with:
* * \e string \b language - 2-letter ISO 639-1 code ("en")
* * \e boolean \b from_url - true if language from URL overrides browser default
*/ */
function determine_help_language() { function determine_help_language() {
$lang_detect = new Text_LanguageDetect(); $lang_detect = new Text_LanguageDetect();
// Set this mode to recognize language by the short code like "en", "ru", etc. // Set this mode to recognize language by the short code like "en", "ru", etc.
$lang_detect->setNameMode(2); $lang_detect->setNameMode(2);
// If the language was specified in the URL, override the language preference
// of the browser. Default to English if both of these are absent.
if($lang_detect->languageExists(argv(1))) { if($lang_detect->languageExists(argv(1))) {
$lang = argv(1); $lang = argv(1);
$from_url = true; $from_url = true;
@ -211,10 +216,10 @@ function find_doc_file($s) {
} }
/** /**
* @brief * @brief Search in doc files.
* *
* @param string $s * @param string $s The search string to search for
* @return number|mixed|unknown|boolean * @return array
*/ */
function search_doc_files($s) { function search_doc_files($s) {
@ -275,7 +280,6 @@ function doc_rank_sort($s1, $s2) {
* *
* @return string * @return string
*/ */
function load_context_help() { function load_context_help() {
$path = App::$cmd; $path = App::$cmd;
@ -305,7 +309,7 @@ function load_context_help() {
* @brief * @brief
* *
* @param string $s * @param string $s
* @return void|boolean[]|number[]|string[]|unknown[] * @return void|array
*/ */
function store_doc_file($s) { function store_doc_file($s) {

5
include/import.php
View File

@ -12,6 +12,7 @@ require_once('include/perm_upgrade.php');
* @param array $channel * @param array $channel
* @param int $account_id * @param int $account_id
* @param int $seize * @param int $seize
* @param string $newname (optional)
* @return boolean|array * @return boolean|array
*/ */
function import_channel($channel, $account_id, $seize, $newname = '') { function import_channel($channel, $account_id, $seize, $newname = '') {
@ -672,7 +673,7 @@ function import_items($channel, $items, $sync = false, $relocate = null) {
/** /**
* @brief Sync items to channel. * @brief Sync items to channel.
* *
* @see import_items * @see import_items()
* *
* @param array $channel where to import to * @param array $channel where to import to
* @param array $items * @param array $items
@ -1049,7 +1050,7 @@ function import_mail($channel, $mails, $sync = false) {
/** /**
* @brief Synchronise mails. * @brief Synchronise mails.
* *
* @see import_mail * @see import_mail()
* @param array $channel * @param array $channel
* @param array $mails * @param array $mails
*/ */

4
include/items.php
View File

@ -3004,7 +3004,9 @@ function tgroup_check($uid, $item) {
* @param array $channel * @param array $channel
* @param array $item * @param array $item
* @param int $item_id * @param int $item_id
* @param boolean $parent * @param array $parent
* @param boolean $edit (optional) default false
* @return void
*/ */
function start_delivery_chain($channel, $item, $item_id, $parent, $edit = false) { function start_delivery_chain($channel, $item, $item_id, $parent, $edit = false) {

13
include/plugin.php
View File

@ -7,11 +7,13 @@
/** /**
* @brief Handle errors in plugin calls * @brief Handle errors in plugin calls.
* *
* @param string $plugin name of the addon * @param string $plugin name of the addon
* @param string $error_text text of error * @param string $notice UI visible text of error
* @param bool $uninstall uninstall plugin * @param string $log technical error message for logging
* @param bool $uninstall (optional) default false
* uninstall plugin on error
*/ */
function handleerrors_plugin($plugin, $notice, $log, $uninstall = false){ function handleerrors_plugin($plugin, $notice, $log, $uninstall = false){
logger("Addons: [" . $plugin . "] Error: ".$log, LOGGER_ERROR); logger("Addons: [" . $plugin . "] Error: ".$log, LOGGER_ERROR);
@ -381,8 +383,6 @@ function unregister_hook($hook, $file, $function) {
* array in their theme_init() and use this to customise the app behaviour. * array in their theme_init() and use this to customise the app behaviour.
* use insert_hook($hookname,$function_name) to do this. * use insert_hook($hookname,$function_name) to do this.
*/ */
function load_hooks() { function load_hooks() {
App::$hooks = []; App::$hooks = [];
@ -1085,10 +1085,11 @@ function get_markup_template($s, $root = '') {
} }
/** /**
* @brief * @brief Test if a folder exists.
* *
* @param string $folder * @param string $folder
* @return boolean|string * @return boolean|string
* False if folder does not exist, or canonicalized absolute pathname
*/ */
function folder_exists($folder) { function folder_exists($folder) {
// Get canonicalized absolute pathname // Get canonicalized absolute pathname

115
include/text.php
View File

@ -44,8 +44,8 @@ function replace_macros($s, $r) {
try { try {
$output = $t->replace_macros($arr['template'], $arr['params']); $output = $t->replace_macros($arr['template'], $arr['params']);
} catch (Exception $e) { } catch (Exception $e) {
logger("Unable to render template: ".$e->getMessage()); logger('Unable to render template: ' . $e->getMessage());
$output = "<h3>ERROR: there was an error creating the output.</h3>"; $output = '<h3>ERROR: there was an error creating the output.</h3>';
} }
return $output; return $output;
@ -539,7 +539,14 @@ function paginate(&$a) {
return $o; return $o;
} }
/**
* @brief
*
* @param int $i
* @param string $more
* @param string $less
* @return string Parsed HTML from template 'alt_pager.tpl'
*/
function alt_pager($i, $more = '', $less = '') { function alt_pager($i, $more = '', $less = '') {
if(! $more) if(! $more)
@ -810,7 +817,7 @@ function activity_match($haystack,$needle) {
* and strip the period from any tags which end with one. * and strip the period from any tags which end with one.
* *
* @param string $s * @param string $s
* @return Returns array of tags found, or empty array. * @return array Returns an array of tags found, or empty array.
*/ */
function get_tags($s) { function get_tags($s) {
$ret = array(); $ret = array();
@ -900,6 +907,7 @@ function tag_sort_length($a,$b) {
function total_sort($a,$b) { function total_sort($a,$b) {
if($a['total'] == $b['total']) if($a['total'] == $b['total'])
return 0; return 0;
return(($b['total'] > $a['total']) ? 1 : (-1)); return(($b['total'] > $a['total']) ? 1 : (-1));
} }
@ -1004,9 +1012,15 @@ function contact_block() {
'$micropro' => $micropro, '$micropro' => $micropro,
)); ));
$arr = array('contacts' => $r, 'output' => $o); $arr = ['contacts' => $r, 'output' => $o];
/**
* @hooks contact_block_end
* Called at the end of contact_block(), but can not manipulate the output.
* * \e array \b contacts - Result array from database
* * \e string \b output - the generated output
*/
call_hooks('contact_block_end', $arr); call_hooks('contact_block_end', $arr);
return $o; return $o;
} }
@ -1108,16 +1122,20 @@ function linkify($s, $me = false) {
* to a local redirector which uses https and which redirects to the selected content * to a local redirector which uses https and which redirects to the selected content
* *
* @param string $s * @param string $s
* @param int $uid
* @returns string * @returns string
*/ */
function sslify($s) { function sslify($s) {
// Local photo cache // Local photo cache
$str = array( $str = [
'body' => $s, 'body' => $s,
'uid' => local_channel() 'uid' => local_channel()
); ];
/**
* @hooks cache_body_hook
* * \e string \b body The content to parse and also the return value
* * \e int|bool \b uid
*/
call_hooks('cache_body_hook', $str); call_hooks('cache_body_hook', $str);
$s = $str['body']; $s = $str['body'];
@ -1222,7 +1240,11 @@ function get_mood_verbs() {
/** /**
* @brief Function to list all smilies, both internal and from addons. * @brief Function to list all smilies, both internal and from addons.
* *
* @return Returns array with keys 'texts' and 'icons' * @param boolean $default_only (optional) default false
* true will prevent that plugins can add smilies
* @return array Returns an associative array with:
* * \e array \b texts
* * \e array \b icons
*/ */
function list_smilies($default_only = false) { function list_smilies($default_only = false) {
@ -1300,6 +1322,11 @@ function list_smilies($default_only = false) {
if($default_only) if($default_only)
return $params; return $params;
/**
* @hooks smile
* * \e array \b texts - default values and also return value
* * \e array \b icons - default values and also return value
*/
call_hooks('smilie', $params); call_hooks('smilie', $params);
return $params; return $params;
@ -1625,6 +1652,10 @@ function generate_named_map($location) {
function prepare_body(&$item,$attach = false,$opts = false) { function prepare_body(&$item,$attach = false,$opts = false) {
/**
* @hooks prepare_body_init
* * \e array \b item
*/
call_hooks('prepare_body_init', $item); call_hooks('prepare_body_init', $item);
$s = ''; $s = '';
@ -1656,13 +1687,19 @@ function prepare_body(&$item,$attach = false,$opts = false) {
$event = (($item['obj_type'] === ACTIVITY_OBJ_EVENT) ? format_event_obj($item['obj']) : false); $event = (($item['obj_type'] === ACTIVITY_OBJ_EVENT) ? format_event_obj($item['obj']) : false);
$prep_arr = array( $prep_arr = [
'item' => $item, 'item' => $item,
'html' => $event ? $event['content'] : $s, 'html' => $event ? $event['content'] : $s,
'event' => $event['header'], 'event' => $event['header'],
'photo' => $photo 'photo' => $photo
); ];
/**
* @hooks prepare_body
* * \e array \b item
* * \e string \b html - the parsed HTML to return
* * \e string \b event - the event header to return
* * \e string \b photo - the photo to return
*/
call_hooks('prepare_body', $prep_arr); call_hooks('prepare_body', $prep_arr);
$s = $prep_arr['html']; $s = $prep_arr['html'];
@ -2249,19 +2286,24 @@ function ids_to_querystr($arr,$idx = 'id',$quote = false) {
} }
/** /**
* @brief array_elm_to_str($arr,$elm,$delim = ',') extract unique individual elements from an array of arrays and return them as a string separated by a delimiter * @brief Extract unique individual elements from an array of arrays and return
* similar to ids_to_querystr, but allows a different delimiter instead of a db-quote option * them as a string separated by a delimiter.
* empty elements (evaluated after trim()) are ignored. *
* @param $arr array * Similar to ids_to_querystr, but allows a different delimiter instead of a
* @param $elm array key to extract from sub-array * db-quote option empty elements (evaluated after trim()) are ignored.
* @param $delim string default ',' *
* @param $each filter function to apply to each element before evaluation, default is 'trim'. * @see ids_to_querystr()
*
* @param array $arr
* @param string $elm key to extract from sub-array
* @param string $delim (optional) default ','
* @param string $each (optional) default is 'trim'
* Filter function to apply to each element before evaluation.
* @returns string * @returns string
*/ */
function array_elm_to_str($arr, $elm, $delim = ',', $each = 'trim') { function array_elm_to_str($arr, $elm, $delim = ',', $each = 'trim') {
$tmp = []; $tmp = [];
if($arr && is_array($arr)) { if($arr && is_array($arr)) {
foreach($arr as $x) { foreach($arr as $x) {
if(is_array($x) && array_key_exists($elm,$x)) { if(is_array($x) && array_key_exists($elm,$x)) {
@ -2272,6 +2314,7 @@ function array_elm_to_str($arr,$elm,$delim = ',',$each = 'trim') {
} }
} }
} }
return implode($delim, $tmp); return implode($delim, $tmp);
} }
@ -2496,9 +2539,9 @@ function design_tools() {
} }
/** /**
* @brief Creates website portation tools menu * @brief Creates website portation tools menu.
* *
* @return string * @return string Parsed HTML code from template 'website_portation_tools.tpl'
*/ */
function website_portation_tools() { function website_portation_tools() {
@ -2511,7 +2554,7 @@ function website_portation_tools() {
$sys = true; $sys = true;
} }
return replace_macros(get_markup_template('website_portation_tools.tpl'), array( return replace_macros(get_markup_template('website_portation_tools.tpl'), [
'$title' => t('Import'), '$title' => t('Import'),
'$import_label' => t('Import website...'), '$import_label' => t('Import website...'),
'$import_placeholder' => t('Select folder to import'), '$import_placeholder' => t('Select folder to import'),
@ -2528,7 +2571,7 @@ function website_portation_tools() {
'$cloud_export_desc' => t('/path/to/export/folder'), '$cloud_export_desc' => t('/path/to/export/folder'),
'$cloud_export_hint' => t('Enter a path to a cloud files destination.'), '$cloud_export_hint' => t('Enter a path to a cloud files destination.'),
'$cloud_export_select' => t('Specify folder'), '$cloud_export_select' => t('Specify folder'),
)); ]);
} }
/** /**
@ -3103,7 +3146,13 @@ function pdl_selector($uid, $current='') {
intval($uid) intval($uid)
); );
$arr = array('channel_id' => $uid, 'current' => $current, 'entries' => $r); $arr = ['channel_id' => $uid, 'current' => $current, 'entries' => $r];
/**
* @hooks pdl_selector
* * \e int \b channel_id
* * \e string \b current
* * \e array \b entries - Result from database query
*/
call_hooks('pdl_selector', $arr); call_hooks('pdl_selector', $arr);
$entries = $arr['entries']; $entries = $arr['entries'];
@ -3178,7 +3227,6 @@ function text_highlight($s, $lang) {
'language' => $lang, 'language' => $lang,
'success' => false 'success' => false
]; ];
/** /**
* @hooks text_highlight * @hooks text_highlight
* * \e string \b text * * \e string \b text
@ -3379,13 +3427,17 @@ function punify($s) {
} }
// Be aware that unpunify will only convert domain names and not pathnames /**
* Be aware that unpunify() will only convert domain names and not pathnames.
*
* @param string $s
* @return string
*/
function unpunify($s) { function unpunify($s) {
require_once('vendor/simplepie/simplepie/idn/idna_convert.class.php'); require_once('vendor/simplepie/simplepie/idn/idna_convert.class.php');
$x = new idna_convert(['encoding' => 'utf8']); $x = new idna_convert(['encoding' => 'utf8']);
return $x->decode($s);
return $x->decode($s);
} }
@ -3529,4 +3581,3 @@ function new_uuid() {
return $hash; return $hash;
} }

4
include/zot.php
View File

@ -174,7 +174,7 @@ function zot_build_packet($channel, $type = 'notify', $recipients = null, $remot
* packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'keychange', 'force_refresh', 'notify', 'auth_check' * packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'keychange', 'force_refresh', 'notify', 'auth_check'
* @param array $recipients * @param array $recipients
* envelope information, array ( 'guid' => string, 'guid_sig' => string ); empty for public posts * envelope information, array ( 'guid' => string, 'guid_sig' => string ); empty for public posts
* @param string msg * @param string $msg
* optional message * optional message
* @param string $remote_key * @param string $remote_key
* optional public site key of target hub used to encrypt entire packet * optional public site key of target hub used to encrypt entire packet
@ -5057,7 +5057,7 @@ function zot_reply_auth_check($data,$encrypted_packet) {
} }
// There should be exactly one recipient, the original auth requestor // There should be exactly one recipient, the original auth requestor
/// @FIXME $recipients is undefined here.
$ret['message'] .= 'recipients ' . print_r($recipients,true) . EOL; $ret['message'] .= 'recipients ' . print_r($recipients,true) . EOL;
if ($data['recipients']) { if ($data['recipients']) {