aboutsummaryrefslogtreecommitdiffstats
path: root/include/PermissionDescription.php
blob: 1f7799406323b9e7a41038a36bde089090612fca (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
<?php

if(class_exists('PermissionDescription')) return;

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 '';
		}
	}

}