aboutsummaryrefslogtreecommitdiffstats
path: root/include/network.php
diff options
context:
space:
mode:
authorKlaus Weidenbach <Klaus.Weidenbach@gmx.net>2017-09-05 00:23:42 +0200
committerKlaus Weidenbach <Klaus.Weidenbach@gmx.net>2017-11-03 23:04:27 +0100
commit1a737be2b408135177a9e94dcffd0f68c0aca90b (patch)
tree17e565688120ef94db2fa1e9635d0d55f2e43c58 /include/network.php
parent0ce7358f0f00cb000562dc34be13459eb5779c18 (diff)
downloadvolse-hubzilla-1a737be2b408135177a9e94dcffd0f68c0aca90b.tar.gz
volse-hubzilla-1a737be2b408135177a9e94dcffd0f68c0aca90b.tar.bz2
volse-hubzilla-1a737be2b408135177a9e94dcffd0f68c0aca90b.zip
:bulb: Improving Doxygen documentation.
Fix some Doxygen parsing errors. Improve hooks documentation.
Diffstat (limited to 'include/network.php')
-rw-r--r--include/network.php214
1 files changed, 141 insertions, 73 deletions
diff --git a/include/network.php b/include/network.php
index 2caf29ab5..3569874be 100644
--- a/include/network.php
+++ b/include/network.php
@@ -1,6 +1,7 @@
<?php
/**
* @file include/network.php
+ * @brief Network related functions.
*/
/**
@@ -189,7 +190,7 @@ function z_fetch_url($url, $binary = false, $redirects = 0, $opts = array()) {
/**
- * @brief
+ * @brief Does a curl post request.
*
* @param string $url
* URL to post
@@ -214,7 +215,7 @@ function z_fetch_url($url, $binary = false, $redirects = 0, $opts = array()) {
* * \e string \b body => content
* * \e string \b debug => from curl_info()
*/
-function z_post_url($url,$params, $redirects = 0, $opts = array()) {
+function z_post_url($url, $params, $redirects = 0, $opts = array()) {
// logger('url: ' . $url);
// logger('params: ' . print_r($params,true));
@@ -276,13 +277,10 @@ function z_post_url($url,$params, $redirects = 0, $opts = array()) {
@curl_setopt($ch, CURLOPT_USERPWD, $opts['http_auth']);
}
-
if(x($opts,'cookiejar'))
@curl_setopt($ch, CURLOPT_COOKIEJAR, $opts['cookiejar']);
if(x($opts,'cookiefile'))
@curl_setopt($ch, CURLOPT_COOKIEFILE, $opts['cookiefile']);
-
-
if(x($opts,'cookie'))
@curl_setopt($ch, CURLOPT_COOKIE, $opts['cookie']);
@@ -423,7 +421,7 @@ function http_status($val, $msg = '') {
* integer HTTP status result value
* @param string $msg
* optional message
- * @return does not return, process is terminated
+ * @return void does not return, process is terminated
*/
function http_status_exit($val, $msg = '') {
http_status($val, $msg);
@@ -431,10 +429,10 @@ function http_status_exit($val, $msg = '') {
}
/**
- * @brief convert an XML document to a normalised, case-corrected array used by webfinger.
+ * @brief Convert an XML document to a normalised, case-corrected array used by webfinger.
*
* @param string|array|SimpleXMLElement $xml_element
- * @param int $recursion_depth[in,out]
+ * @param[in,out] int $recursion_depth
* @return NULL|string|array
*/
function convert_xml_element_to_array($xml_element, &$recursion_depth=0) {
@@ -501,14 +499,14 @@ function z_dns_check($h,$check_mx = 0) {
}
/**
- * @brief Validates a given URL
+ * @brief Validates a given URL.
*
* Take a URL from the wild, prepend http:// if necessary and check DNS to see
* if it's real (or check if is a valid IP address).
*
* @see z_dns_check()
*
- * @param string $url[in,out] URL to check
+ * @param[in,out] string $url URL to check
* @return boolean Return true if it's OK, false if something is wrong with it
*/
function validate_url(&$url) {
@@ -593,6 +591,7 @@ function allowed_url($url) {
}
}
}
+
return $found;
}
@@ -658,7 +657,7 @@ function allowed_email($email) {
-function parse_xml_string($s,$strict = true) {
+function parse_xml_string($s, $strict = true) {
if($strict) {
if(! strstr($s,'<?xml'))
return false;
@@ -683,14 +682,21 @@ function parse_xml_string($s,$strict = true) {
return $x;
}
-
+/**
+ * @brief Scales an external image.
+ *
+ * @param string $s
+ * @param string $include_link default true
+ * @param string $scale_replace default false
+ * @return string
+ */
function scale_external_images($s, $include_link = true, $scale_replace = false) {
// Picture addresses can contain special characters
$s = htmlspecialchars_decode($s, ENT_COMPAT);
$matches = null;
- $c = preg_match_all('/\[([zi])mg(.*?)\](.*?)\[\/[zi]mg\]/ism',$s,$matches,PREG_SET_ORDER);
+ $c = preg_match_all('/\[([zi])mg(.*?)\](.*?)\[\/[zi]mg\]/ism', $s, $matches, PREG_SET_ORDER);
if($c) {
require_once('include/photo/photo_driver.php');
@@ -717,22 +723,21 @@ function scale_external_images($s, $include_link = true, $scale_replace = false)
else
$scaled = $mtch[3];
- if(! strpbrk(substr($scaled,0,1),'zhfmt'))
+ if(! strpbrk(substr($scaled, 0, 1), 'zhfmt'))
continue;
- $i = z_fetch_url($scaled,true);
-
+ $i = z_fetch_url($scaled, true);
- $cache = get_config('system','itemcache');
+ $cache = get_config('system', 'itemcache');
if (($cache != '') and is_dir($cache)) {
- $cachefile = $cache."/".hash("md5", $scaled);
+ $cachefile = $cache . '/' . hash('md5', $scaled);
file_put_contents($cachefile, $i['body']);
}
// guess mimetype from headers or filename
- $type = guess_image_type($mtch[3],$i['header']);
- if(strpos($type,'image') === false)
+ $type = guess_image_type($mtch[3], $i['header']);
+ if(strpos($type, 'image') === false)
continue;
if($i['success']) {
@@ -764,7 +769,7 @@ function scale_external_images($s, $include_link = true, $scale_replace = false)
// replace the special char encoding
- $s = htmlspecialchars($s,ENT_COMPAT,'UTF-8');
+ $s = htmlspecialchars($s, ENT_COMPAT, 'UTF-8');
return $s;
}
@@ -1141,7 +1146,14 @@ function discover_by_url($url, $arr = null) {
return true;
}
-function discover_by_webbie($webbie,$protocol = '') {
+/**
+ * @brief
+ *
+ * @param string $webbie
+ * @param string $protocol (optional) default empty
+ * @return boolean
+ */
+function discover_by_webbie($webbie, $protocol = '') {
$result = [];
@@ -1149,7 +1161,7 @@ function discover_by_webbie($webbie,$protocol = '') {
// $webbie = strtolower($webbie);
- $x = webfinger_rfc7033($webbie,true);
+ $x = webfinger_rfc7033($webbie, true);
if($x && array_key_exists('links',$x) && $x['links']) {
foreach($x['links'] as $link) {
if(array_key_exists('rel',$link)) {
@@ -1158,7 +1170,7 @@ function discover_by_webbie($webbie,$protocol = '') {
// here.
if($link['rel'] === PROTOCOL_ZOT && ((! $protocol) || (strtolower($protocol) === 'zot'))) {
- logger('discover_by_webbie: zot found for ' . $webbie, LOGGER_DEBUG);
+ logger('zot found for ' . $webbie, LOGGER_DEBUG);
if(array_key_exists('zot',$x) && $x['zot']['success']) {
$i = import_xchan($x['zot']);
return true;
@@ -1178,16 +1190,35 @@ function discover_by_webbie($webbie,$protocol = '') {
logger('webfinger: ' . print_r($x,true), LOGGER_DATA, LOG_INFO);
- $arr = array('address' => $webbie, 'protocol' => $protocol, 'success' => false, 'webfinger' => $x);
+ $arr = [
+ 'address' => $webbie,
+ 'protocol' => $protocol,
+ 'success' => false,
+ 'webfinger' => $x
+ ];
+ /**
+ * @hooks discover_channel_webfinger
+ * Called when performing a webfinger lookup.
+ * * \e string \b address - The webbie
+ * * \e string \b protocol
+ * * \e array \b webfinger - The result from webfinger_rfc7033()
+ * * \e boolean \b success - The return value, default false
+ */
call_hooks('discover_channel_webfinger', $arr);
if($arr['success'])
return true;
return false;
-
}
-function webfinger_rfc7033($webbie,$zot = false) {
+/**
+ * @brief Fetch and return a webfinger for a webbie.
+ *
+ * @param string $webbie - The webbie
+ * @param boolean $zot (optional) default false
+ * @return boolean|string false or associative array from result JSON
+ */
+function webfinger_rfc7033($webbie, $zot = false) {
if(strpos($webbie,'@')) {
$lhs = substr($webbie,0,strpos($webbie,'@'));
@@ -1199,6 +1230,7 @@ function webfinger_rfc7033($webbie,$zot = false) {
if($m) {
if($m['scheme'] !== 'https')
return false;
+
$rhs = $m['host'] . (($m['port']) ? ':' . $m['port'] : '');
$resource = urlencode($webbie);
}
@@ -1211,20 +1243,19 @@ function webfinger_rfc7033($webbie,$zot = false) {
// and results in a 406 (Not Acceptable) response, and will also incorrectly produce an XML
// document if you use 'application/jrd+json, */*'. We could set this to application/jrd+json,
// but some test webfinger servers may not explicitly set the content type and they would be
- // blocked. The best compromise until Mastodon is fixed is to remove the Accept header which is
- // accomplished by setting it to nothing.
+ // blocked. The best compromise until Mastodon is fixed is to remove the Accept header which is
+ // accomplished by setting it to nothing.
$counter = 0;
- $s = z_fetch_url('https://' . $rhs . '/.well-known/webfinger?f=&resource=' . $resource . (($zot) ? '&zot=1' : ''),
+ $s = z_fetch_url('https://' . $rhs . '/.well-known/webfinger?f=&resource=' . $resource . (($zot) ? '&zot=1' : ''),
false, $counter, [ 'headers' => [ 'Accept:' ] ]);
if($s['success']) {
- $j = json_decode($s['body'],true);
+ $j = json_decode($s['body'], true);
return($j);
}
return false;
-
}
function old_webfinger($webbie) {
@@ -1604,7 +1635,13 @@ function check_siteallowed($url) {
$retvalue = true;
$arr = array('url' => $url);
- call_hooks('check_siteallowed',$arr);
+ /**
+ * @hooks check_siteallowed
+ * Used to over-ride or bypass the site black/white block lists.
+ * * \e string \b url
+ * * \e boolean \b allowed - optional return value set in hook
+ */
+ call_hooks('check_siteallowed', $arr);
if(array_key_exists('allowed',$arr))
return $arr['allowed'];
@@ -1643,7 +1680,13 @@ function check_channelallowed($hash) {
$retvalue = true;
$arr = array('hash' => $hash);
- call_hooks('check_channelallowed',$arr);
+ /**
+ * @hooks check_channelallowed
+ * Used to over-ride or bypass the channel black/white block lists.
+ * * \e string \b hash
+ * * \e boolean \b allowed - optional return value set in hook
+ */
+ call_hooks('check_channelallowed', $arr);
if(array_key_exists('allowed',$arr))
return $arr['allowed'];
@@ -1732,6 +1775,10 @@ function network_to_name($s) {
NETWORK_MYSPACE => t('MySpace'),
);
+ /**
+ * @hooks network_to_name
+ * @deprecated
+ */
call_hooks('network_to_name', $nets);
$search = array_keys($nets);
@@ -1743,7 +1790,7 @@ function network_to_name($s) {
/**
* @brief Send a text email message.
*
- * @param array $params an assoziative array with:
+ * @param array $params an associative array with:
* * \e string \b fromName name of the sender
* * \e string \b fromEmail email of the sender
* * \e string \b replyTo replyTo address to direct responses
@@ -1774,6 +1821,10 @@ function z_mail($params) {
$params['sent'] = false;
$params['result'] = false;
+ /**
+ * @hooks email_send
+ * * \e params @see z_mail()
+ */
call_hooks('email_send', $params);
if($params['sent']) {
@@ -1921,60 +1972,78 @@ function service_plink($contact, $guid) {
$plink = $url . '/channel/' . $handle . '?f=&mid=' . $guid;
$x = [ 'xchan' => $contact, 'guid' => $guid, 'url' => $url, 'plink' => $plink ];
+ /**
+ * @hooks service_plink
+ * * \e array \b xchan
+ * * \e string \b guid
+ * * \e string \b url
+ * * \e string \b plink will get returned
+ */
call_hooks('service_plink', $x);
return $x['plink'];
}
+
+/**
+ * @brief
+ *
+ * @param array $mimeTypes
+ * @param string $acceptedTypes by default false will use $_SERVER['HTTP_ACCEPT']
+ * @return array|NULL
+ */
function getBestSupportedMimeType($mimeTypes = null, $acceptedTypes = false) {
- // Values will be stored in this array
+ // Values will be stored in this array
+ $AcceptTypes = [];
if($acceptedTypes === false)
$acceptedTypes = $_SERVER['HTTP_ACCEPT'];
- $AcceptTypes = Array ();
-
- // Accept header is case insensitive, and whitespace isn’t important
- $accept = strtolower(str_replace(' ', '', $acceptedTypes));
- // divide it into parts in the place of a ","
- $accept = explode(',', $accept);
- foreach ($accept as $a) {
- // the default quality is 1.
- $q = 1;
- // check if there is a different quality
- if (strpos($a, ';q=')) {
- // divide "mime/type;q=X" into two parts: "mime/type" i "X"
- list($a, $q) = explode(';q=', $a);
- }
- // mime-type $a is accepted with the quality $q
- // WARNING: $q == 0 means, that mime-type isn’t supported!
- $AcceptTypes[$a] = $q;
- }
- arsort($AcceptTypes);
-
- // if no parameter was passed, just return parsed data
- if (!$mimeTypes) return $AcceptTypes;
-
- $mimeTypes = array_map('strtolower', (array)$mimeTypes);
-
- // let’s check our supported types:
- foreach ($AcceptTypes as $mime => $q) {
- if ($q && in_array($mime, $mimeTypes)) return $mime;
- }
- // no mime-type found
- return null;
-}
+ // Accept header is case insensitive, and whitespace isn’t important
+ $accept = strtolower(str_replace(' ', '', $acceptedTypes));
+ // divide it into parts in the place of a ","
+ $accept = explode(',', $accept);
+ foreach ($accept as $a) {
+ // the default quality is 1.
+ $q = 1;
+ // check if there is a different quality
+ if (strpos($a, ';q=')) {
+ // divide "mime/type;q=X" into two parts: "mime/type" i "X"
+ list($a, $q) = explode(';q=', $a);
+ }
+ // mime-type $a is accepted with the quality $q
+ // WARNING: $q == 0 means, that mime-type isn’t supported!
+ $AcceptTypes[$a] = $q;
+ }
+ arsort($AcceptTypes);
+ // if no parameter was passed, just return parsed data
+ if (!$mimeTypes) return $AcceptTypes;
-function jsonld_document_loader($url) {
+ $mimeTypes = array_map('strtolower', (array)$mimeTypes);
- // perform caching for jsonld normaliser
+ // let’s check our supported types:
+ foreach ($AcceptTypes as $mime => $q) {
+ if ($q && in_array($mime, $mimeTypes)) return $mime;
+ }
+
+ // no mime-type found
+ return null;
+}
+
+/**
+ * @brief Perform caching for jsonld normaliser.
+ *
+ * @param string $url
+ * @return mixed|boolean|array
+ */
+function jsonld_document_loader($url) {
require_once('library/jsonld/jsonld.php');
$cachepath = 'store/[data]/ldcache';
if(! is_dir($cachepath))
- os_mkdir($cachepath,STORAGE_DEFAULT_PERMISSIONS,true);
+ os_mkdir($cachepath, STORAGE_DEFAULT_PERMISSIONS, true);
$filename = $cachepath . '/' . urlencode($url);
if(file_exists($filename) && filemtime($filename) > time() - (12 * 60 * 60)) {
@@ -1983,7 +2052,7 @@ function jsonld_document_loader($url) {
$r = jsonld_default_document_loader($url);
if($r) {
- file_put_contents($filename,json_encode($r));
+ file_put_contents($filename, json_encode($r));
return $r;
}
@@ -1993,5 +2062,4 @@ function jsonld_document_loader($url) {
}
return [];
-
} \ No newline at end of file