move permissiondescription class to zotlabs/lib

10 files changed, 180 insertions, 22 deletions

diff --git a/Zotlabs/Lib/PermissionDescription.php b/Zotlabs/Lib/PermissionDescription.php
new file mode 100644
index 000000000..55aac2dea
--- /dev/null
+++ b/Zotlabs/Lib/PermissionDescription.php
@@ -0,0 +1,170 @@
+<?php
+
+namespace Zotlabs\Lib;
+
+require_once("include/permissions.php");
+require_once("include/language.php");
+require_once("include/text.php");
+
+
+/**
+ * Encapsulates information the ACL dialog requires to describe
+ * permission settings for an item with an empty ACL.
+ * i.e the caption, icon, and tooltip for the no-ACL option in the ACL dialog.
+ */
+class PermissionDescription  {
+
+	private $global_perm;
+	private $channel_perm;
+	private $fallback_description;
+	
+	/**
+	 * Constructor is private.
+	 * Use static methods fromGlobalPermission(), fromStandalonePermission(), or fromDescription()
+	 * to create instances.
+	 */
+	private function __construct($global_perm, $channel_perm, $description = '') {
+
+		$this->global_perm  = $global_perm;
+		$this->channel_perm = $channel_perm;
+		
+		$this->fallback_description = ($description  == '') ? t('Visible to your default audience') : $description;
+	}
+
+	/**
+	 * If the interpretation of an empty ACL can't be summarised with a global default permission
+	 * or a specific permission setting then use this method and describe what it means instead.
+	 * Remember to localize the description first.
+	 *
+	 * @param  string $description - the localized caption for the no-ACL option in the ACL dialog.
+	 * @return a new instance of PermissionDescription
+	 */
+	public static function fromDescription($description) {
+		return new PermissionDescription('', 0x80000, $description);
+	}
+
+
+	/**
+	 * Use this method only if the interpretation of an empty ACL doesn't fall back to a global
+	 * default permission. You should pass one of the constants from boot.php - PERMS_PUBLIC,
+	 * PERMS_NETWORK etc.
+	 * 
+	 * @param  integer $perm - a single enumerated constant permission - PERMS_PUBLIC, PERMS_NETWORK etc.
+	 * @return a new instance of PermissionDescription
+	 */
+	public static function fromStandalonePermission($perm) {
+
+		$result = new PermissionDescription('', $perm);
+		
+		$checkPerm = $this->get_permission_description();
+		if ($checkPerm == $this->fallback_description) {
+			$result = null;
+			logger('null PermissionDescription from unknown standalone permission: ' . $perm ,LOGGER_DEBUG, LOG_ERROR);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * This is the preferred way to create a PermissionDescription, as it provides the most details.
+	 * Use this method if you know an empty ACL will result in one of the global default permissions 
+	 * being used, such as channel_r_stream (for which you would pass 'view_stream').
+	 * 
+	 * @param  string $permname - a key for the global perms array from get_perms() in permissions.php,
+	 *         e.g. 'view_stream', 'view_profile', etc.
+	 * @return a new instance of PermissionDescription
+	 */
+	public static function fromGlobalPermission($permname) {
+
+		$result = null;
+
+		$global_perms = get_perms();
+
+		if (array_key_exists($permname, $global_perms)) {
+
+			$permDetails = $global_perms[$permname];
+
+			// It should be OK to always just read the permissions from App::$channel
+			//
+			// App::$profile is a union of channel and profile fields.
+			// The distinction is basically that App::$profile is pointing to the resource
+			// being observed. App::$channel is referring to the current logged-in channel
+			// member (if this is a local channel) e.g. the observer. We only show the ACL
+			// widget to the page owner (observer and observed are the same) so in that case
+			// I believe either may be safely used here.
+			$channelPerm = \App::$channel[$permDetails[0]];
+			$result = new PermissionDescription($permDetails[1], $channelPerm);
+		} else {
+			// The acl dialog can handle null arguments, but it shouldn't happen
+			logger('null PermissionDescription from unknown global permission: ' . $permname ,LOGGER_DEBUG, LOG_ERROR);
+		}
+		return $result;
+	}
+
+
+	/**
+	 * Gets a localized description of the permission, or a generic message if the permission
+	 * is unknown.
+	 *
+	 * @return string description
+	 */
+	public function get_permission_description() {
+
+		switch($this->channel_perm) {			
+
+			case 0:              return t('Only me');
+			case PERMS_PUBLIC:   return t('Public');
+			case PERMS_NETWORK:  return t('Anybody in the $Projectname network');
+			case PERMS_SITE:     return sprintf(t('Any account on %s'), \App::get_hostname());
+			case PERMS_CONTACTS: return t('Any of my connections');
+			case PERMS_SPECIFIC: return t('Only connections I specifically allow');
+			case PERMS_AUTHED:   return t('Anybody authenticated (could include visitors from other networks)');
+			case PERMS_PENDING:  return t('Any connections including those who haven\'t yet been approved');
+			default:             return $this->fallback_description;
+		}
+	}
+
+	/**
+	 * Returns an icon css class name if an appropriate one is available, e.g. "fa-globe" for Public,
+	 * otherwise returns empty string. 
+	 *
+	 * @return string icon css class name (often FontAwesome)
+	 */
+	public function get_permission_icon() {
+
+		switch($this->channel_perm) {			
+
+			case 0:/* only me */ return 'fa-eye-slash';
+			case PERMS_PUBLIC:   return 'fa-globe';
+			case PERMS_NETWORK:  return 'fa-share-alt-square'; // fa-share-alt-square is very similiar to the hubzilla logo, but we should create our own logo class to use
+			case PERMS_SITE:     return 'fa-sitemap'; 
+			case PERMS_CONTACTS: return 'fa-group'; 
+			case PERMS_SPECIFIC: return 'fa-list';
+			case PERMS_AUTHED:   return '';
+			case PERMS_PENDING:  return '';
+			default:             return '';
+		}
+	}
+
+
+	/**
+	 * Returns a localized description of where the permission came from, if this is known.
+	 * If it's not know, or if the permission is standalone and didn't come from a default
+	 * permission setting, then empty string is returned.
+	 *
+	 * @return string description or empty string
+	*/
+	public function get_permission_origin_description() {
+
+		switch($this->global_perm) {			
+
+			case PERMS_R_STREAM:  return t('This is your default setting for the audience of your normal stream, and posts.');
+			case PERMS_R_PROFILE: return t('This is your default setting for who can view your default channel profile');
+			case PERMS_R_ABOOK:   return t('This is your default setting for who can view your connections');
+			case PERMS_R_STORAGE: return t('This is your default setting for who can view your file storage and photos');
+			case PERMS_R_PAGES:   return t('This is your default setting for the audience of your webpages');
+			default:              return '';
+		}
+	}
+
+}
diff --git a/Zotlabs/Module/Channel.php b/Zotlabs/Module/Channel.php
index d09388901..c74802ec5 100644
--- a/Zotlabs/Module/Channel.php
+++ b/Zotlabs/Module/Channel.php
@@ -9,7 +9,6 @@ require_once('include/security.php');
 require_once('include/conversation.php');
 require_once('include/acl_selectors.php');
 require_once('include/permissions.php');
-require_once('include/PermissionDescription.php');
 
 class Channel extends \Zotlabs\Web\Controller {
 
@@ -133,7 +132,7 @@ class Channel extends \Zotlabs\Web\Controller {
 					'default_location' => (($is_owner) ? \App::$profile['channel_location'] : ''),
 					'nickname' => \App::$profile['channel_address'],
 					'lockstate' => (((strlen(\App::$profile['channel_allow_cid'])) || (strlen(\App::$profile['channel_allow_gid'])) || (strlen(\App::$profile['channel_deny_cid'])) || (strlen(\App::$profile['channel_deny_gid']))) ? 'lock' : 'unlock'),
-					'acl' => (($is_owner) ? populate_acl($channel_acl,true, \PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post') : ''),
+					'acl' => (($is_owner) ? populate_acl($channel_acl,true, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post') : ''),
 					'showacl' => (($is_owner) ? 'yes' : ''),
 					'bang' => '',
 					'visitor' => (($is_owner || $observer) ? true : false),
diff --git a/Zotlabs/Module/Editwebpage.php b/Zotlabs/Module/Editwebpage.php
index 5cd409e1e..be4803a07 100644
--- a/Zotlabs/Module/Editwebpage.php
+++ b/Zotlabs/Module/Editwebpage.php
@@ -4,7 +4,6 @@ namespace Zotlabs\Module;
 require_once('include/channel.php');
 require_once('include/acl_selectors.php');
 require_once('include/conversation.php');
-require_once('include/PermissionDescription.php');
 
 
 class Editwebpage extends \Zotlabs\Web\Controller {
@@ -151,7 +150,7 @@ class Editwebpage extends \Zotlabs\Web\Controller {
 			'body' => undo_post_tagging($itm[0]['body']),
 			'post_id' => $post_id,
 			'visitor' => ($is_owner) ? true : false,
-			'acl' => populate_acl($itm[0],false,\PermissionDescription::fromGlobalPermission('view_pages')),
+			'acl' => populate_acl($itm[0],false,\Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_pages')),
 			'showacl' => ($is_owner) ? true : false,
 			'mimetype' => $mimetype,
 			'mimeselect' => true,
diff --git a/Zotlabs/Module/Events.php b/Zotlabs/Module/Events.php
index 3187cddb4..def5c437b 100644
--- a/Zotlabs/Module/Events.php
+++ b/Zotlabs/Module/Events.php
@@ -6,7 +6,6 @@ require_once('include/bbcode.php');
 require_once('include/datetime.php');
 require_once('include/event.php');
 require_once('include/items.php');
-require_once('include/PermissionDescription.php');
 
 
 class Events extends \Zotlabs\Web\Controller {
@@ -471,7 +470,7 @@ class Events extends \Zotlabs\Web\Controller {
 				'$permissions' => t('Permission settings'),
 				// populating the acl dialog was a permission description from view_stream because Cal.php, which
 				// displays events, says "since we don't currently have an event permission - use the stream permission"
-				'$acl' => (($orig_event['event_xchan']) ? '' : populate_acl(((x($orig_event)) ? $orig_event : $perm_defaults), false, \PermissionDescription::fromGlobalPermission('view_stream'))),
+				'$acl' => (($orig_event['event_xchan']) ? '' : populate_acl(((x($orig_event)) ? $orig_event : $perm_defaults), false, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_stream'))),
 				'$submit' => t('Submit'),
 				'$advanced' => t('Advanced Options')
 	
diff --git a/Zotlabs/Module/Filestorage.php b/Zotlabs/Module/Filestorage.php
index 2861f31be..c3ef22e32 100644
--- a/Zotlabs/Module/Filestorage.php
+++ b/Zotlabs/Module/Filestorage.php
@@ -6,7 +6,6 @@ namespace Zotlabs\Module;
  */
 
 require_once('include/attach.php');
-require_once('include/PermissionDescription.php');
 
 
 /**
@@ -134,7 +133,7 @@ class Filestorage extends \Zotlabs\Web\Controller {
 			$cloudpath = get_cloudpath($f) . (intval($f['is_dir']) ? '?f=&davguest=1' : '');
 			$parentpath = get_parent_cloudpath($channel['channel_id'], $channel['channel_address'], $f['hash']);
 	
-			$aclselect_e = populate_acl($f, false, \PermissionDescription::fromGlobalPermission('view_storage'));
+			$aclselect_e = populate_acl($f, false, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_storage'));
 			$is_a_dir = (intval($f['is_dir']) ? true : false);
 	
 			$lockstate = (($f['allow_cid'] || $f['allow_gid'] || $f['deny_cid'] || $f['deny_gid']) ? 'lock' : 'unlock'); 
diff --git a/Zotlabs/Module/Network.php b/Zotlabs/Module/Network.php
index 87ed326e2..3b88cd8d6 100644
--- a/Zotlabs/Module/Network.php
+++ b/Zotlabs/Module/Network.php
@@ -6,8 +6,6 @@ require_once('include/group.php');
 require_once('include/contact_widgets.php');
 require_once('include/conversation.php');
 require_once('include/acl_selectors.php');
-require_once('include/PermissionDescription.php');
-
 
 
 class Network extends \Zotlabs\Web\Controller {
@@ -171,7 +169,7 @@ class Network extends \Zotlabs\Web\Controller {
 				'default_location' => $channel['channel_location'],
 				'nickname'         => $channel['channel_address'],
 				'lockstate'        => (($private_editing || $channel['channel_allow_cid'] || $channel['channel_allow_gid'] || $channel['channel_deny_cid'] || $channel['channel_deny_gid']) ? 'lock' : 'unlock'),
-				'acl'              => populate_acl((($private_editing) ? $def_acl : $channel_acl), true, \PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post'),
+				'acl'              => populate_acl((($private_editing) ? $def_acl : $channel_acl), true, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post'),
 				'bang'             => (($private_editing) ? '!' : ''),
 				'visitor'          => true,
 				'profile_uid'      => local_channel(),
diff --git a/Zotlabs/Module/Photos.php b/Zotlabs/Module/Photos.php
index 1633e08ef..1eeab1461 100644
--- a/Zotlabs/Module/Photos.php
+++ b/Zotlabs/Module/Photos.php
@@ -9,8 +9,6 @@ require_once('include/bbcode.php');
 require_once('include/security.php');
 require_once('include/attach.php');
 require_once('include/text.php');
-require_once('include/PermissionDescription.php');
-
 
 
 class Photos extends \Zotlabs\Web\Controller {
@@ -633,7 +631,7 @@ class Photos extends \Zotlabs\Web\Controller {
 				$lockstate = (($acl->is_private()) ? 'lock' : 'unlock');
 			}
 	
-			$aclselect = (($_is_owner) ? populate_acl($channel_acl,false, \PermissionDescription::fromGlobalPermission('view_storage')) : '');
+			$aclselect = (($_is_owner) ? populate_acl($channel_acl,false, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_storage')) : '');
 	
 			// this is wrong but is to work around an issue with js_upload wherein it chokes if these variables
 			// don't exist. They really should be set to a parseable representation of the channel's default permissions 
@@ -1023,7 +1021,7 @@ class Photos extends \Zotlabs\Web\Controller {
 			if($can_post) {
 				$album_e = $ph[0]['album'];
 				$caption_e = $ph[0]['description'];
-				$aclselect_e = (($_is_owner) ? populate_acl($ph[0], true, \PermissionDescription::fromGlobalPermission('view_storage')) : '');
+				$aclselect_e = (($_is_owner) ? populate_acl($ph[0], true, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_storage')) : '');
 				$albums = ((array_key_exists('albums', \App::$data)) ? \App::$data['albums'] : photos_albums_list(\App::$data['channel'],\App::$data['observer']));
 	
 				$_SESSION['album_return'] = bin2hex($ph[0]['album']);
diff --git a/Zotlabs/Module/Rpost.php b/Zotlabs/Module/Rpost.php
index 1396f2a55..32d52c30c 100644
--- a/Zotlabs/Module/Rpost.php
+++ b/Zotlabs/Module/Rpost.php
@@ -7,7 +7,6 @@ require_once('include/items.php');
 require_once('include/taxonomy.php');
 require_once('include/conversation.php');
 require_once('include/zot.php');
-require_once('include/PermissionDescription.php');
 
 /**
  * remote post
@@ -116,7 +115,7 @@ class Rpost extends \Zotlabs\Web\Controller {
 			'default_location' => $channel['channel_location'],
 			'nickname' => $channel['channel_address'],
 			'lockstate' => (($acl->is_private()) ? 'lock' : 'unlock'),
-			'acl' => populate_acl($channel_acl, true, \PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post'),
+			'acl' => populate_acl($channel_acl, true, Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_stream'), get_post_aclDialogDescription(), 'acl_dialog_post'),
 			'bang' => '',
 			'visitor' => true,
 			'profile_uid' => local_channel(),
diff --git a/Zotlabs/Module/Settings.php b/Zotlabs/Module/Settings.php
index 875004fae..af246a4dc 100644
--- a/Zotlabs/Module/Settings.php
+++ b/Zotlabs/Module/Settings.php
@@ -2,8 +2,6 @@
 namespace Zotlabs\Module; /** @file */
 
 require_once('include/zot.php');
-require_once('include/PermissionDescription.php');
-
 
 
 class Settings extends \Zotlabs\Web\Controller {
@@ -1066,7 +1064,7 @@ class Settings extends \Zotlabs\Web\Controller {
 				'$maxreq' 	=> array('maxreq', t('Maximum Friend Requests/Day:'), intval($channel['channel_max_friend_req']) , t('May reduce spam activity')),
 				'$permissions' => t('Default Post and Publish Permissions'),
 				'$permdesc' => t("\x28click to open/close\x29"),
-				'$aclselect' => populate_acl($perm_defaults, false, \PermissionDescription::fromDescription(t('Use my default audience setting for the type of object published'))),
+				'$aclselect' => populate_acl($perm_defaults, false, \Zotlabs\Lib\PermissionDescription::fromDescription(t('Use my default audience setting for the type of object published'))),
 				'$suggestme' => $suggestme,
 				'$group_select' => $group_select,
 				'$role' => array('permissions_role' , t('Channel permissions category:'), $permissions_role, '', get_roles()),
diff --git a/Zotlabs/Module/Webpages.php b/Zotlabs/Module/Webpages.php
index bb8d9c6ed..cc0a01cce 100644
--- a/Zotlabs/Module/Webpages.php
+++ b/Zotlabs/Module/Webpages.php
@@ -4,7 +4,6 @@ namespace Zotlabs\Module;
 require_once('include/channel.php');
 require_once('include/conversation.php');
 require_once('include/acl_selectors.php');
-require_once('include/PermissionDescription.php');
 
 
 class Webpages extends \Zotlabs\Web\Controller {
@@ -105,7 +104,7 @@ class Webpages extends \Zotlabs\Web\Controller {
 			'is_owner' => true,
 			'nickname' => \App::$profile['channel_address'],
 			'lockstate' => (($channel['channel_allow_cid'] || $channel['channel_allow_gid'] || $channel['channel_deny_cid'] || $channel['channel_deny_gid']) ? 'lock' : 'unlock'),
-			'acl' => (($is_owner) ? populate_acl($channel_acl,false, \PermissionDescription::fromGlobalPermission('view_pages')) : ''),
+			'acl' => (($is_owner) ? populate_acl($channel_acl,false, \Zotlabs\Lib\PermissionDescription::fromGlobalPermission('view_pages')) : ''),
 			'showacl' => (($is_owner) ? true : false),
 			'visitor' => true,
 			'hide_location' => true,