includes/utils/MWGrants.php

   1 <?php
   2 /**
   3  * Functions and constants to deal with grants
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  */
  20
  21 /**
  22  * A collection of public static functions to deal with grants.
  23  */
  24 class MWGrants {
  25
  26         /**
  27          * List all known grants.
  28          * @return array
  29          */
  30         public static function getValidGrants() {
  31                 global $wgGrantPermissions;
  32
  33                 return array_keys( $wgGrantPermissions );
  34         }
  35
  36         /**
  37          * Map all grants to corresponding user rights.
  38          * @return array grant => array of rights
  39          */
  40         public static function getRightsByGrant() {
  41                 global $wgGrantPermissions;
  42
  43                 $res = [];
  44                 foreach ( $wgGrantPermissions as $grant => $rights ) {
  45                         $res[$grant] = array_keys( array_filter( $rights ) );
  46                 }
  47                 return $res;
  48         }
  49
  50         /**
  51          * Fetch the display name of the grant
  52          * @param string $grant
  53          * @param Language|string|null $lang
  54          * @return string Grant description
  55          */
  56         public static function grantName( $grant, $lang = null ) {
  57                 // Give grep a chance to find the usages:
  58                 // grant-blockusers, grant-createeditmovepage, grant-delete,
  59                 // grant-editinterface, grant-editmycssjs, grant-editmywatchlist,
  60                 // grant-editpage, grant-editprotected, grant-highvolume,
  61                 // grant-oversight, grant-patrol, grant-protect, grant-rollback,
  62                 // grant-sendemail, grant-uploadeditmovefile, grant-uploadfile,
  63                 // grant-basic, grant-viewdeleted, grant-viewmywatchlist,
  64                 // grant-createaccount
  65                 $msg = wfMessage( "grant-$grant" );
  66                 if ( $lang !== null ) {
  67                         if ( is_string( $lang ) ) {
  68                                 $lang = Language::factory( $lang );
  69                         }
  70                         $msg->inLanguage( $lang );
  71                 }
  72                 if ( !$msg->exists() ) {
  73                         $msg = wfMessage( 'grant-generic', $grant );
  74                         if ( $lang ) {
  75                                 $msg->inLanguage( $lang );
  76                         }
  77                 }
  78                 return $msg->text();
  79         }
  80
  81         /**
  82          * Fetch the display names for the grants.
  83          * @param string[] $grants
  84          * @param Language|string|null $lang
  85          * @return string[] Corresponding grant descriptions
  86          */
  87         public static function grantNames( array $grants, $lang = null ) {
  88                 if ( $lang !== null ) {
  89                         if ( is_string( $lang ) ) {
  90                                 $lang = Language::factory( $lang );
  91                         }
  92                 }
  93
  94                 $ret = [];
  95                 foreach ( $grants as $grant ) {
  96                         $ret[] = self::grantName( $grant, $lang );
  97                 }
  98                 return $ret;
  99         }
 100
 101         /**
 102          * Fetch the rights allowed by a set of grants.
 103          * @param string[]|string $grants
 104          * @return string[]
 105          */
 106         public static function getGrantRights( $grants ) {
 107                 global $wgGrantPermissions;
 108
 109                 $rights = [];
 110                 foreach ( (array)$grants as $grant ) {
 111                         if ( isset( $wgGrantPermissions[$grant] ) ) {
 112                                 $rights = array_merge( $rights, array_keys( array_filter( $wgGrantPermissions[$grant] ) ) );
 113                         }
 114                 }
 115                 return array_unique( $rights );
 116         }
 117
 118         /**
 119          * Test that all grants in the list are known.
 120          * @param string[] $grants
 121          * @return bool
 122          */
 123         public static function grantsAreValid( array $grants ) {
 124                 return array_diff( $grants, self::getValidGrants() ) === [];
 125         }
 126
 127         /**
 128          * Divide the grants into groups.
 129          * @param string[]|null $grantsFilter
 130          * @return array Map of (group => (grant list))
 131          */
 132         public static function getGrantGroups( $grantsFilter = null ) {
 133                 global $wgGrantPermissions, $wgGrantPermissionGroups;
 134
 135                 if ( is_array( $grantsFilter ) ) {
 136                         $grantsFilter = array_flip( $grantsFilter );
 137                 }
 138
 139                 $groups = [];
 140                 foreach ( $wgGrantPermissions as $grant => $rights ) {
 141                         if ( $grantsFilter !== null && !isset( $grantsFilter[$grant] ) ) {
 142                                 continue;
 143                         }
 144                         if ( isset( $wgGrantPermissionGroups[$grant] ) ) {
 145                                 $groups[$wgGrantPermissionGroups[$grant]][] = $grant;
 146                         } else {
 147                                 $groups['other'][] = $grant;
 148                         }
 149                 }
 150
 151                 return $groups;
 152         }
 153
 154         /**
 155          * Get the list of grants that are hidden and should always be granted
 156          * @return string[]
 157          */
 158         public static function getHiddenGrants() {
 159                 global $wgGrantPermissionGroups;
 160
 161                 $grants = [];
 162                 foreach ( $wgGrantPermissionGroups as $grant => $group ) {
 163                         if ( $group === 'hidden' ) {
 164                                 $grants[] = $grant;
 165                         }
 166                 }
 167                 return $grants;
 168         }
 169
 170         /**
 171          * Generate a link to Special:ListGrants for a particular grant name.
 172          *
 173          * This should be used to link end users to a full description of what
 174          * rights they are giving when they authorize a grant.
 175          *
 176          * @param string $grant the grant name
 177          * @param Language|string|null $lang
 178          * @return string (proto-relative) HTML link
 179          */
 180         public static function getGrantsLink( $grant, $lang = null ) {
 181                 return \Linker::linkKnown(
 182                         \SpecialPage::getTitleFor( 'Listgrants', false, $grant ),
 183                         htmlspecialchars( self::grantName( $grant, $lang ) )
 184                 );
 185         }
 186
 187         /**
 188          * Generate wikitext to display a list of grants
 189          * @param string[]|null $grantsFilter If non-null, only display these grants.
 190          * @param Language|string|null $lang
 191          * @return string Wikitext
 192          */
 193         public static function getGrantsWikiText( $grantsFilter, $lang = null ) {
 194                 global $wgContLang;
 195
 196                 if ( is_string( $lang ) ) {
 197                         $lang = Language::factory( $lang );
 198                 } elseif ( $lang === null ) {
 199                         $lang = $wgContLang;
 200                 }
 201
 202                 $s = '';
 203                 foreach ( self::getGrantGroups( $grantsFilter ) as $group => $grants ) {
 204                         if ( $group === 'hidden' ) {
 205                                 continue; // implicitly granted
 206                         }
 207                         $s .= "*<span class=\"mw-grantgroup\">" .
 208                                 wfMessage( "grant-group-$group" )->inLanguage( $lang )->text() . "</span>\n";
 209                         $s .= ":" . $lang->semicolonList( self::grantNames( $grants, $lang ) ) . "\n";
 210                 }
 211                 return "$s\n";
 212         }
 213
 214 }