diff options
Diffstat (limited to 'Zotlabs/Access/Permissions.php')
| -rw-r--r-- | Zotlabs/Access/Permissions.php | 158 |
1 files changed, 106 insertions, 52 deletions
diff --git a/Zotlabs/Access/Permissions.php b/Zotlabs/Access/Permissions.php index d51e4d0ea..74286934f 100644 --- a/Zotlabs/Access/Permissions.php +++ b/Zotlabs/Access/Permissions.php @@ -1,45 +1,52 @@ <?php - namespace Zotlabs\Access; use Zotlabs\Lib as Zlib; +/** + * @brief Extensible permissions. + * + * To add new permissions, add to the list of $perms below, with a simple description. + * + * Also visit PermissionRoles.php and add to the $ret['perms_connect'] property for any role + * if this permission should be granted to new connections. + * + * Next look at PermissionRoles::new_custom_perms() and provide a handler for updating custom + * permission roles. You will want to set a default PermissionLimit for each channel and also + * provide a sane default for any existing connections. You may or may not wish to provide a + * default auto permission. If in doubt, leave this alone as custom permissions by definition + * are the responsibility of the channel owner to manage. You just don't want to create any + * suprises or break things so you have an opportunity to provide sane settings. + * + * Update the version here and in PermissionRoles. + * + * + * Permissions with 'view' in the name are considered read permissions. Anything + * else requires authentication. Read permission limits are PERMS_PUBLIC and anything else + * is given PERMS_SPECIFIC. + * + * PermissionLimits::Std_limits() retrieves the standard limits. A permission role + * MAY alter an individual setting after retrieving the Std_limits if you require + * something different for a specific permission within the given role. + * + */ class Permissions { - /** - * Extensible permissions. - * To add new permissions, add to the list of $perms below, with a simple description. - * - * Also visit PermissionRoles.php and add to the $ret['perms_connect'] property for any role - * if this permission should be granted to new connections. - * - * Next look at PermissionRoles::new_custom_perms() and provide a handler for updating custom - * permission roles. You will want to set a default PermissionLimit for each channel and also - * provide a sane default for any existing connections. You may or may not wish to provide a - * default auto permission. If in doubt, leave this alone as custom permissions by definition - * are the responsibility of the channel owner to manage. You just don't want to create any - * suprises or break things so you have an opportunity to provide sane settings. - * - * Update the version here and in PermissionRoles - * - * - * Permissions with 'view' in the name are considered read permissions. Anything - * else requires authentication. Read permission limits are PERMS_PUBLIC and anything else - * is given PERMS_SPECIFIC. - * - * PermissionLimits::Std_limits() retrieves the standard limits. A permission role - * MAY alter an individual setting after retrieving the Std_limits if you require - * something different for a specific permission within the given role. - * - */ - static public function version() { // This must match the version in PermissionRoles.php before permission updates can run. return 2; } - + /** + * @brief Return an array with Permissions. + * + * @hooks permissions_list + * * \e array \b permissions + * * \e string \b filter + * @param string $filter (optional) only passed to hook permission_list + * @return Associative array with permissions and short description. + */ static public function Perms($filter = '') { $perms = [ @@ -63,18 +70,27 @@ class Permissions { 'delegate' => t('Can administer my channel') ]; - $x = array('permissions' => $perms, 'filter' => $filter); - call_hooks('permissions_list',$x); - return($x['permissions']); + $x = [ + 'permissions' => $perms, + 'filter' => $filter + ]; + call_hooks('permissions_list', $x); + return($x['permissions']); } + /** + * @brief Perms from the above list that are blocked from anonymous observers. + * + * e.g. you must be authenticated. + * + * @hooks write_perms + * * \e array \b permissions + * @return Associative array with permissions and short description. + */ static public function BlockedAnonPerms() { - // Perms from the above list that are blocked from anonymous observers. - // e.g. you must be authenticated. - - $res = array(); + $res = []; $perms = PermissionLimits::Std_limits(); foreach($perms as $perm => $limit) { if($limit != PERMS_PUBLIC) { @@ -82,17 +98,22 @@ class Permissions { } } - $x = array('permissions' => $res); - call_hooks('write_perms',$x); - return($x['permissions']); + $x = ['permissions' => $res]; + call_hooks('write_perms', $x); + return($x['permissions']); } - // converts [ 0 => 'view_stream', ... ] - // to [ 'view_stream' => 1 ] - // for any permissions in $arr; - // Undeclared permissions are set to 0 - + /** + * @brief Converts indexed perms array to associative perms array. + * + * Converts [ 0 => 'view_stream', ... ] + * to [ 'view_stream' => 1 ] for any permissions in $arr; + * Undeclared permissions which exist in Perms() are added and set to 0. + * + * @param array $arr + * @return array + */ static public function FilledPerms($arr) { if(is_null($arr)) { btlogger('FilledPerms: null'); @@ -101,15 +122,26 @@ class Permissions { $everything = self::Perms(); $ret = []; foreach($everything as $k => $v) { - if(in_array($k,$arr)) + if(in_array($k, $arr)) $ret[$k] = 1; else $ret[$k] = 0; } - return $ret; + return $ret; } + /** + * @brief Convert perms array to indexed array. + * + * Converts [ 'view_stream' => 1 ] for any permissions in $arr + * to [ 0 => ['name' => 'view_stream', 'value' => 1], ... ] + * + * @param array $arr associative perms array 'view_stream' => 1 + * @return Indexed array with elements that look like + * * \e string \b name the perm name (e.g. view_stream) + * * \e int \b value the value of the perm (e.g. 1) + */ static public function OPerms($arr) { $ret = []; if($arr) { @@ -120,7 +152,12 @@ class Permissions { return $ret; } - + /** + * @brief + * + * @param int $channel_id + * @return boolean|array + */ static public function FilledAutoperms($channel_id) { if(! intval(get_pconfig($channel_id,'system','autoperms'))) return false; @@ -137,16 +174,33 @@ class Permissions { return $arr; } - static public function PermsCompare($p1,$p2) { + /** + * @brief Compares that all Permissions from $p1 exist also in $p2. + * + * @param array $p1 The perms that have to exist in $p2 + * @param array $p2 The perms to compare against + * @return boolean true if all perms from $p1 exist also in $p2 + */ + static public function PermsCompare($p1, $p2) { foreach($p1 as $k => $v) { - if(! array_key_exists($k,$p2)) + if(! array_key_exists($k, $p2)) return false; + if($p1[$k] != $p2[$k]) return false; } + return true; } + /** + * @brief + * + * @param int $channel_id A channel id + * @return associative array + * * \e array \b perms Permission array + * * \e int \b automatic 0 or 1 + */ static public function connect_perms($channel_id) { $my_perms = []; @@ -155,7 +209,7 @@ class Permissions { // If a default permcat exists, use that - $pc = ((feature_enabled($channel_id,'permcats')) ? get_pconfig($channel_id,'system','default_permcat') : 'default'); + $pc = ((feature_enabled($channel_id,'permcats')) ? get_pconfig($channel_id,'system','default_permcat') : 'default'); if(! in_array($pc, [ '','default' ])) { $pcp = new Zlib\Permcat($channel_id); $permcat = $pcp->fetch($pc); @@ -167,7 +221,7 @@ class Permissions { } // look up the permission role to see if it specified auto-connect - // and if there was no permcat or a default permcat, set the perms + // and if there was no permcat or a default permcat, set the perms // from the role $role = get_pconfig($channel_id,'system','permissions_role'); @@ -195,7 +249,7 @@ class Permissions { } // If we reached this point with no permissions, the channel is using - // custom perms but they are not automatic. They will be stored in abconfig with + // custom perms but they are not automatic. They will be stored in abconfig with // the channel's channel_hash (the 'self' connection). if(! $my_perms) { |