Merge branch 'doku' into 'dev'

Extend documentation.

See merge request hubzilla/core!1496

1 files changed, 239 insertions, 136 deletions

diff --git a/Zotlabs/Lib/Apps.php b/Zotlabs/Lib/Apps.php
index de7439ed7..9edd00667 100644
--- a/Zotlabs/Lib/Apps.php
+++ b/Zotlabs/Lib/Apps.php
@@ -1,32 +1,34 @@
-<?php /** @file */
+<?php
 
 namespace Zotlabs\Lib;
 
-/**
- * Apps
- *
- */
-
 require_once('include/plugin.php');
 require_once('include/channel.php');
 
-
+/**
+ * @brief Apps class.
+ *
+ */
 class Apps {
 
 	static public $available_apps = null;
 	static public $installed_apps = null;
-
 	static public $base_apps = null;
 
-
-
+	/**
+	 * @brief
+	 *
+	 * @param boolean $translate (optional) default true
+	 * @return array
+	 */
 	static public function get_system_apps($translate = true) {
+		$ret = [];
 
-		$ret = array();
 		if(is_dir('apps'))
 			$files = glob('apps/*.apd');
 		else
 			$files = glob('app/*.apd');
+
 		if($files) {
 			foreach($files as $f) {
 				$x = self::parse_app_description($f,$translate);
@@ -50,14 +52,17 @@ class Apps {
 			}
 		}
 
-		call_hooks('get_system_apps',$ret);
+		/**
+		 * @hooks get_system_apps
+		 *   Hook to manipulate the system apps array.
+		 */
+		call_hooks('get_system_apps', $ret);
 
 		return $ret;
-
 	}
 
 	static public function get_base_apps() {
-		$x = get_config('system','base_apps',[ 
+		$x = get_config('system','base_apps',[
 			'Connections',
 			'Network',
 			'Settings',
@@ -72,7 +77,13 @@ class Apps {
 			'Mail',
 			'Profile Photo'
 		]);
-		call_hooks('get_base_apps',$x);
+
+		/**
+		 * @hooks get_base_apps
+		 *   Hook to manipulate the base apps array.
+		 */
+		call_hooks('get_base_apps', $x);
+
 		return $x;
 	}
 
@@ -81,7 +92,7 @@ class Apps {
 			return;
 
 		self::$base_apps = self::get_base_apps();
- 
+
 		$apps = self::get_system_apps(false);
 
 		self::$available_apps = q("select * from app where app_channel = 0");
@@ -106,6 +117,7 @@ class Apps {
 				// $id will be boolean true or false to install an app, or an integer id to update an existing app
 				if($id === false)
 					continue;
+
 				if($id !== true) {
 					// if we already installed this app, but it changed, preserve any categories we created
 					$s = EMPTY_STR;
@@ -126,16 +138,17 @@ class Apps {
 				$app['guid'] = hash('whirlpool',$app['name']);
 				$app['system'] = 1;
 				self::app_install(local_channel(),$app);
-
 			}
-		}					
+		}
 	}
 
 	/**
-	 * Install the system app if no system apps have been installed, or if a new system app 
+	 * Install the system app if no system apps have been installed, or if a new system app
 	 * is discovered, or if the version of a system app changes.
+	 *
+	 * @param array $app
+	 * @return boolean|int
 	 */
-
 	static public function check_install_system_app($app) {
 		if((! is_array(self::$available_apps)) || (! count(self::$available_apps))) {
 			return true;
@@ -159,17 +172,16 @@ class Apps {
 		return $notfound;
 	}
 
-
 	/**
-	 * Install the system app if no system apps have been installed, or if a new system app 
-	 * is discovered, or if the version of a system app changes.
+	 * Install the personal app if no personal apps have been installed, or if a new personal app
+	 * is discovered, or if the version of a personal app changes.
+	 *
+	 * @param array $app
+	 * @return boolean|int
 	 */
-
-
-
 	static public function check_install_personal_app($app) {
 		$installed = false;
-		foreach(self::$installed_apps as $iapp) {			
+		foreach(self::$installed_apps as $iapp) {
 			if($iapp['app_id'] == hash('whirlpool',$app['name'])) {
 				$installed = true;
 				if(($iapp['app_version'] != $app['version'])
@@ -189,19 +201,24 @@ class Apps {
 		return strcasecmp($a['name'],$b['name']);
 	}
 
-
-	static public function parse_app_description($f,$translate = true) {
-
-		$ret = array();
+	/**
+	 * @brief Parse app description.
+	 *
+	 * @param string $f filename
+	 * @param boolean $translate (optional) default true
+	 * @return boolean|array
+	 */
+	static public function parse_app_description($f, $translate = true) {
+		$ret = [];
+		$matches = [];
 
 		$baseurl = z_root();
-		$channel = \App::get_channel();
-		$address = (($channel) ? $channel['channel_address'] : '');
-		
+		//$channel = \App::get_channel();
+		//$address = (($channel) ? $channel['channel_address'] : '');
+
 		//future expansion
 
 		$observer = \App::get_observer();
-	
 
 		$lines = @file($f);
 		if($lines) {
@@ -210,7 +227,7 @@ class Apps {
 					$ret[$matches[1]] = trim($matches[2]);
 				}
 			}
-		}	
+		}
 
 		if(! $ret['photo'])
 			$ret['photo'] = $baseurl . '/' . get_default_profile_photo(80);
@@ -292,10 +309,12 @@ class Apps {
 		if($ret) {
 			if($translate)
 				self::translate_system_apps($ret);
+
 			return $ret;
 		}
+
 		return false;
-	}	
+	}
 
 
 	static public function translate_system_apps(&$arr) {
@@ -311,17 +330,17 @@ class Apps {
 			'Remote Diagnostics' => t('Remote Diagnostics'),
 			'Suggest Channels' => t('Suggest Channels'),
 			'Login' => t('Login'),
-			'Channel Manager' => t('Channel Manager'), 
+			'Channel Manager' => t('Channel Manager'),
 			'Network' => t('Stream'),
 			'Settings' => t('Settings'),
 			'Files' => t('Files'),
 			'Webpages' => t('Webpages'),
 			'Wiki' => t('Wiki'),
-			'Channel Home' => t('Channel Home'), 
+			'Channel Home' => t('Channel Home'),
 			'View Profile' => t('View Profile'),
-			'Photos' => t('Photos'), 
-			'Events' => t('Events'), 
-			'Directory' => t('Directory'), 
+			'Photos' => t('Photos'),
+			'Events' => t('Events'),
+			'Directory' => t('Directory'),
 			'Help' => t('Help'),
 			'Mail' => t('Mail'),
 			'Mood' => t('Mood'),
@@ -366,30 +385,31 @@ class Apps {
 				if(array_key_exists($arr[$x]['name'],$apps)) {
 					$arr[$x]['name'] = $apps[$arr[$x]['name']];
 				} else {
-				    // Try to guess by app name if not in list
-				    $arr[$x]['name'] = t(trim($arr[$x]['name']));
+					// Try to guess by app name if not in list
+					$arr[$x]['name'] = t(trim($arr[$x]['name']));
 				}
 			}
 		}
-				
 	}
 
-
-	// papp is a portable app
-
-	static public function app_render($papp,$mode = 'view') {
-
-		/**
-		 * modes:
-		 *    view: normal mode for viewing an app via bbcode from a conversation or page
-		 *       provides install/update button if you're logged in locally
-		 *    install: like view but does not display app-bin options if they are present
-		 *    list: normal mode for viewing an app on the app page
-		 *       no buttons are shown
-		 *    edit: viewing the app page in editing mode provides a delete button
-		 *    nav: render apps for app-bin
-		 */
-
+	/**
+	 * @brief
+	 *
+	 * @param array $papp
+	 *  papp is a portable app
+	 * @param string $mode (optional) default 'view'
+	 *   Render modes:
+	 *   * \b view: normal mode for viewing an app via bbcode from a conversation or page
+	 *       provides install/update button if you're logged in locally
+	 *   * \b install: like view but does not display app-bin options if they are present
+	 *   * \b list: normal mode for viewing an app on the app page
+	 *       no buttons are shown
+	 *   * \b edit: viewing the app page in editing mode provides a delete button
+	 *   * \b nav: render apps for app-bin
+	 *
+	 * @return void|string Parsed HTML
+	 */
+	static public function app_render($papp, $mode = 'view') {
 		$installed = false;
 
 		if(! $papp)
@@ -414,7 +434,7 @@ class Apps {
 				$sys = get_sys_channel();
 				$view_channel = $sys['channel_id'];
 			}
-			self::app_macros($view_channel,$papp); 
+			self::app_macros($view_channel,$papp);
 		}
 
 		if(strpos($papp['url'], ',')) {
@@ -427,7 +447,6 @@ class Apps {
 			$papp['url'] = z_root() . ((strpos($papp['url'],'/') === 0) ? '' : '/') . $papp['url'];
 
 
-
 		foreach($papp as $k => $v) {
 			if(strpos($v,'http') === 0 && $k != 'papp') {
 				if(! (local_channel() && strpos($v,z_root()) === 0)) {
@@ -509,7 +528,7 @@ class Apps {
 				if($x) {
 					$hosturl = $x['scheme'] . '://' . $x['host'] . '/';
 				}
-			} 
+			}
 		}
 
 		$install_action = (($installed) ? t('Update') : t('Install'));
@@ -592,8 +611,14 @@ class Apps {
 		return false;
 	}
 
-
-	static public function can_delete($uid,$app) {
+	/**
+	 * @brief
+	 *
+	 * @param mixed $uid If not set return false, otherwise no influence
+	 * @param array $app
+	 * @return boolean
+	 */
+	static public function can_delete($uid, $app) {
 		if(! $uid) {
 			return false;
 		}
@@ -601,7 +626,7 @@ class Apps {
 		$base_apps = self::get_base_apps();
 		if($base_apps) {
 			foreach($base_apps as $b) {
-				if($app['guid'] === hash('whirlpool',$b)) {
+				if($app['guid'] === hash('whirlpool', $b)) {
 					return false;
 				}
 			}
@@ -613,7 +638,6 @@ class Apps {
 	static public function app_destroy($uid,$app) {
 
 		if($uid && $app['guid']) {
-
 			$x = q("select * from app where app_id = '%s' and app_channel = %d limit 1",
 				dbesc($app['guid']),
 				intval($uid)
@@ -622,7 +646,7 @@ class Apps {
 				if(! intval($x[0]['app_deleted'])) {
 					$x[0]['app_deleted'] = 1;
 					if(self::can_delete($uid,$app)) {
-						$r = q("delete from app where app_id = '%s' and app_channel = %d",
+						q("delete from app where app_id = '%s' and app_channel = %d",
 							dbesc($app['guid']),
 							intval($uid)
 						);
@@ -630,10 +654,15 @@ class Apps {
 							intval(TERM_OBJ_APP),
 							intval($x[0]['id'])
 						);
+						/**
+						 * @hooks app_destroy
+						 *  Called after app entry got removed from database
+						 *  and provide app array from database.
+						 */
 						call_hooks('app_destroy', $x[0]);
 					}
 					else {
-						$r = q("update app set app_deleted = 1 where app_id = '%s' and app_channel = %d",
+						q("update app set app_deleted = 1 where app_id = '%s' and app_channel = %d",
 							dbesc($app['guid']),
 							intval($uid)
 						);
@@ -647,22 +676,23 @@ class Apps {
 				}
 			}
 		}
-
 	}
 
-	static public function app_undestroy($uid,$app) {
-
-		// undelete a system app
-		
+	/**
+	 * @brief Undelete a system app.
+	 *
+	 * @param int $uid
+	 * @param array $app
+	 */
+	static public function app_undestroy($uid, $app) {
 		if($uid && $app['guid']) {
-
 			$x = q("select * from app where app_id = '%s' and app_channel = %d limit 1",
 				dbesc($app['guid']),
 				intval($uid)
 			);
 			if($x) {
 				if($x[0]['app_system']) {
-					$r = q("update app set app_deleted = 0 where app_id = '%s' and app_channel = %d",
+					q("update app set app_deleted = 0 where app_id = '%s' and app_channel = %d",
 						dbesc($app['guid']),
 						intval($uid)
 					);
@@ -671,7 +701,15 @@ class Apps {
 		}
 	}
 
-	static public function app_feature($uid,$app,$term) {
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param array $app
+	 * @param string $term
+	 * @return void
+	 */
+	static public function app_feature($uid, $app, $term) {
 		$r = q("select id from app where app_id = '%s' and app_channel = %d limit 1",
 			dbesc($app['guid']),
 			intval($uid)
@@ -695,23 +733,37 @@ class Apps {
 		}
 	}
 
-	static public function app_installed($uid,$app,$bypass_filter=false) {
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param array $app
+	 * @param boolean $bypass_filter (optional) default false
+	 * @return boolean
+	 */
+	static public function app_installed($uid, $app, $bypass_filter = false) {
 
 		$r = q("select id from app where app_id = '%s' and app_channel = %d limit 1",
-			dbesc((array_key_exists('guid',$app)) ? $app['guid'] : ''), 
+			dbesc((array_key_exists('guid', $app)) ? $app['guid'] : ''),
 			intval($uid)
 		);
-		if (!$bypass_filter) {
+		if(!$bypass_filter) {
 			$filter_arr = [
-				'uid'=>$uid,
-				'app'=>$app,
-				'installed'=>$r
+				'uid' => $uid,
+				'app' => $app,
+				'installed' => $r
 			];
-			call_hooks('app_installed_filter',$filter_arr);
+			/**
+			 * @hooks app_installed_filter
+			 *  * \e int \b uid
+			 *  * \e array \b app
+			 *  * \e mixed \b installed - return value
+			 */
+			call_hooks('app_installed_filter', $filter_arr);
 			$r = $filter_arr['installed'];
 		}
-		return(($r) ? true : false);
 
+		return(($r) ? true : false);
 	}
 
 
@@ -727,11 +779,17 @@ class Apps {
 				'app'=>$app,
 				'installed'=>$r
 			];
-			call_hooks('addon_app_installed_filter',$filter_arr);
+			/**
+			 * @hooks addon_app_installed_filter
+			 *  * \e int \b uid
+			 *  * \e array \b app
+			 *  * \e mixed \b installed - return value
+			 */
+			call_hooks('addon_app_installed_filter', $filter_arr);
 			$r = $filter_arr['installed'];
 		}
-		return(($r) ? true : false);
 
+		return(($r) ? true : false);
 	}
 
 	static public function system_app_installed($uid,$app,$bypass_filter=false) {
@@ -746,28 +804,39 @@ class Apps {
 				'app'=>$app,
 				'installed'=>$r
 			];
-			call_hooks('system_app_installed_filter',$filter_arr);
+			/**
+			 * @hooks system_app_installed_filter
+			 *  * \e int \b uid
+			 *  * \e array \b app
+			 *  * \e mixed \b installed - return value
+			 */
+			call_hooks('system_app_installed_filter', $filter_arr);
 			$r = $filter_arr['installed'];
 		}
-		return(($r) ? true : false);
 
+		return(($r) ? true : false);
 	}
 
-
-
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param boolean $deleted
+	 * @param array $cats
+	 * @return boolean|array
+	 */
 	static public function app_list($uid, $deleted = false, $cats = []) {
-		if($deleted) 
-			$sql_extra = "";
+		if($deleted)
+			$sql_extra = '';
 		else
-			$sql_extra = " and app_deleted = 0 ";
+			$sql_extra = ' and app_deleted = 0 ';
 
 		if($cats) {
-
-			$cat_sql_extra = " and ( ";
+			$cat_sql_extra = ' and ( ';
 
 			foreach($cats as $cat) {
 				if(strpos($cat_sql_extra, 'term'))
-					$cat_sql_extra .= "or ";
+					$cat_sql_extra .= 'or ';
 
 				$cat_sql_extra .= "term = '" . dbesc($cat) . "' ";
 			}
@@ -779,11 +848,13 @@ class Apps {
 			);
 			if(! $r)
 				return $r;
-			$sql_extra .= " and app.id in ( ";
+
+			$sql_extra .= ' and app.id in ( ';
 			$s = '';
 			foreach($r as $rr) {
 				if($s)
 					$s .= ',';
+
 				$s .= intval($rr['oid']);
 			}
 			$sql_extra .= $s . ') ';
@@ -794,12 +865,26 @@ class Apps {
 		);
 
 		if($r) {
-                        $hookinfo = Array('uid'=>$uid,'deleted'=>$deleted,'cats'=>$cats,'apps'=>$r);
-			call_hooks('app_list',$hookinfo);
+			$hookinfo = [
+					'uid' => $uid,
+					'deleted' => $deleted,
+					'cats' => $cats,
+					'apps' => $r,
+			];
+			/**
+			 * @hooks app_list
+			 *  * \e int \b uid
+			 *  * \e boolean \b deleted
+			 *  * \e array \b cats
+			 *  * \e array \b apps - return value
+			 */
+			call_hooks('app_list', $hookinfo);
 			$r = $hookinfo['apps'];
-			for($x = 0; $x < count($r); $x ++) {
+
+			for($x = 0; $x < count($r); $x++) {
 				if(! $r[$x]['app_system'])
 					$r[$x]['type'] = 'personal';
+
 				$r[$x]['term'] = q("select * from term where otype = %d and oid = %d",
 					intval(TERM_OBJ_APP),
 					intval($r[$x]['id'])
@@ -807,7 +892,7 @@ class Apps {
 			}
 		}
 
-		return($r);
+		return $r;
 	}
 
 	static public function app_order($uid,$apps,$menu) {
@@ -839,13 +924,14 @@ class Apps {
 				$ret[] = $ap;
 			}
 		}
-		return $ret;
 
+		return $ret;
 	}
 
 	static function find_app_in_array($name,$arr) {
 		if(! $arr)
 			return false;
+
 		foreach($arr as $x) {
 			if($x['name'] === $name) {
 					return $x;
@@ -854,8 +940,16 @@ class Apps {
 		return false;
 	}
 
-	static function moveup($uid,$guid,$menu) {
-		$syslist = array();
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param int $guid
+	 * @param string $menu
+	 * @return void
+	 */
+	static function moveup($uid, $guid, $menu) {
+		$syslist = [];
 
 		$conf = (($menu === 'nav_featured_app') ? 'app_order' : 'app_pin_order');
 
@@ -865,6 +959,7 @@ class Apps {
 				$papp = self::app_encode($li);
 				if($menu !== 'nav_pinned_app' && strpos($papp['categories'],'nav_pinned_app') !== false)
 					continue;
+
 				$syslist[] = $papp;
 			}
 		}
@@ -877,8 +972,6 @@ class Apps {
 		if(! $syslist)
 			return;
 
-		$newlist = [];
-
 		foreach($syslist as $k => $li) {
 			if($li['guid'] === $guid) {
 				$position = $k;
@@ -887,6 +980,7 @@ class Apps {
 		}
 		if(! $position)
 			return;
+
 		$dest_position = $position - 1;
 		$saved = $syslist[$dest_position];
 		$syslist[$dest_position] = $syslist[$position];
@@ -898,11 +992,18 @@ class Apps {
 		}
 
 		set_pconfig($uid,'system',$conf,implode(',',$narr));
-
 	}
 
-	static function movedown($uid,$guid,$menu) {
-		$syslist = array();
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param int $guid
+	 * @param string $menu
+	 * @return void
+	 */
+	static function movedown($uid, $guid, $menu) {
+		$syslist = [];
 
 		$conf = (($menu === 'nav_featured_app') ? 'app_order' : 'app_pin_order');
 
@@ -912,6 +1013,7 @@ class Apps {
 				$papp = self::app_encode($li);
 				if($menu !== 'nav_pinned_app' && strpos($papp['categories'],'nav_pinned_app') !== false)
 					continue;
+
 				$syslist[] = $papp;
 			}
 		}
@@ -924,8 +1026,6 @@ class Apps {
 		if(! $syslist)
 			return;
 
-		$newlist = [];
-
 		foreach($syslist as $k => $li) {
 			if($li['guid'] === $guid) {
 				$position = $k;
@@ -934,6 +1034,7 @@ class Apps {
 		}
 		if($position >= count($syslist) - 1)
 			return;
+
 		$dest_position = $position + 1;
 		$saved = $syslist[$dest_position];
 		$syslist[$dest_position] = $syslist[$position];
@@ -945,7 +1046,6 @@ class Apps {
 		}
 
 		set_pconfig($uid,'system',$conf,implode(',',$narr));
-
 	}
 
 	static public function app_decode($s) {
@@ -953,8 +1053,14 @@ class Apps {
 		return json_decode($x,true);
 	}
 
-
-	static public function app_macros($uid,&$arr) {
+	/**
+	 * @brief
+	 *
+	 * @param int $uid
+	 * @param[in,out] array $arr
+	 * @return void
+	 */
+	static public function app_macros($uid, &$arr) {
 
 		if(! intval($uid))
 			return;
@@ -962,21 +1068,17 @@ class Apps {
 		$baseurl = z_root();
 		$channel = channelx_by_n($uid);
 		$address = (($channel) ? $channel['channel_address'] : '');
-		
+
 		//future expansion
 
-		$observer = \App::get_observer();
-	
+		//$observer = \App::get_observer();
+
 		$arr['url'] = str_replace(array('$baseurl','$nick'),array($baseurl,$address),$arr['url']);
 		$arr['photo'] = str_replace(array('$baseurl','$nick'),array($baseurl,$address),$arr['photo']);
-
 	}
 
 
 
-
-
-
 	static public function app_store($arr) {
 
 		//logger('app_store: ' . print_r($arr,true));
@@ -1160,16 +1262,20 @@ class Apps {
 		}
 
 		return $ret;
-
 	}
 
-
-	static public function app_encode($app,$embed = false) {
-
-		$ret = array();
+	/**
+	 * @brief
+	 *
+	 * @param array $app
+	 * @param boolean $embed (optional) default false
+	 * @return array|string
+	 */
+	static public function app_encode($app, $embed = false) {
+		$ret = [];
 
 		$ret['type'] = 'personal';
-	
+
 		if($app['app_id'])
 			$ret['guid'] = $app['app_id'];
 
@@ -1202,7 +1308,7 @@ class Apps {
 
 		if($app['app_price'])
 			$ret['price'] = $app['app_price'];
-	
+
 		if($app['app_page'])
 			$ret['page'] = $app['app_page'];
 
@@ -1226,12 +1332,12 @@ class Apps {
 			foreach($app['term'] as $t) {
 				if($s)
 					$s .= ',';
+
 				$s .= $t['term'];
 			}
 			$ret['categories'] = $s;
 		}
 
-
 		if(! $embed)
 			return $ret;
 
@@ -1239,18 +1345,15 @@ class Apps {
 
 		if(array_key_exists('categories',$ret))
 			unset($ret['categories']);
-	
+
 		$j = json_encode($ret);
-		return '[app]' . chunk_split(base64_encode($j),72,"\n") . '[/app]';
 
+		return '[app]' . chunk_split(base64_encode($j),72,"\n") . '[/app]';
 	}
 
 
 	static public function papp_encode($papp) {
 		return chunk_split(base64_encode(json_encode($papp)),72,"\n");
-
 	}
 
 }
-
-