includes/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 use MediaWiki\MediaWikiServices;
  21
  22 /**
  23  * A collection of public static functions to deal with grants.
  24  */
  25 class MWGrants {
  26
  27         /**
  28          * List all known grants.
  29          * @return array
  30          */
  31         public static function getValidGrants() {
  32                 global $wgGrantPermissions;
  33
  34                 return array_keys( $wgGrantPermissions );
  35         }
  36
  37         /**
  38          * Map all grants to corresponding user rights.
  39          * @return array grant => array of rights
  40          */
  41         public static function getRightsByGrant() {
  42                 global $wgGrantPermissions;
  43
  44                 $res = [];
  45                 foreach ( $wgGrantPermissions as $grant => $rights ) {
  46                         $res[$grant] = array_keys( array_filter( $rights ) );
  47                 }
  48                 return $res;
  49         }
  50
  51         /**
  52          * Fetch the display name of the grant
  53          * @param string $grant
  54          * @param Language|string|null $lang
  55          * @return string Grant description
  56          */
  57         public static function grantName( $grant, $lang = null ) {
  58                 // Give grep a chance to find the usages:
  59                 // grant-blockusers, grant-createeditmovepage, grant-delete,
  60                 // grant-editinterface, grant-editmycssjs, grant-editmywatchlist,
  61                 // grant-editpage, grant-editprotected, grant-highvolume,
  62                 // grant-oversight, grant-patrol, grant-protect, grant-rollback,
  63                 // grant-sendemail, grant-uploadeditmovefile, grant-uploadfile,
  64                 // grant-basic, grant-viewdeleted, grant-viewmywatchlist,
  65                 // grant-createaccount
  66                 $msg = wfMessage( "grant-$grant" );
  67                 if ( $lang !== null ) {
  68                         if ( is_string( $lang ) ) {
  69                                 $lang = Language::factory( $lang );
  70                         }
  71                         $msg->inLanguage( $lang );
  72                 }
  73                 if ( !$msg->exists() ) {
  74                         $msg = wfMessage( 'grant-generic', $grant );
  75                         if ( $lang ) {
  76                                 $msg->inLanguage( $lang );
  77                         }
  78                 }
  79                 return $msg->text();
  80         }
  81
  82         /**
  83          * Fetch the display names for the grants.
  84          * @param string[] $grants
  85          * @param Language|string|null $lang
  86          * @return string[] Corresponding grant descriptions
  87          */
  88         public static function grantNames( array $grants, $lang = null ) {
  89                 if ( $lang !== null ) {
  90                         if ( is_string( $lang ) ) {
  91                                 $lang = Language::factory( $lang );
  92                         }
  93                 }
  94
  95                 $ret = [];
  96                 foreach ( $grants as $grant ) {
  97                         $ret[] = self::grantName( $grant, $lang );
  98                 }
  99                 return $ret;
 100         }
 101
 102         /**
 103          * Fetch the rights allowed by a set of grants.
 104          * @param string[]|string $grants
 105          * @return string[]
 106          */
 107         public static function getGrantRights( $grants ) {
 108                 global $wgGrantPermissions;
 109
 110                 $rights = [];
 111                 foreach ( (array)$grants as $grant ) {
 112                         if ( isset( $wgGrantPermissions[$grant] ) ) {
 113                                 $rights = array_merge( $rights, array_keys( array_filter( $wgGrantPermissions[$grant] ) ) );
 114                         }
 115                 }
 116                 return array_unique( $rights );
 117         }
 118
 119         /**
 120          * Test that all grants in the list are known.
 121          * @param string[] $grants
 122          * @return bool
 123          */
 124         public static function grantsAreValid( array $grants ) {
 125                 return array_diff( $grants, self::getValidGrants() ) === [];
 126         }
 127
 128         /**
 129          * Divide the grants into groups.
 130          * @param string[]|null $grantsFilter
 131          * @return array Map of (group => (grant list))
 132          */
 133         public static function getGrantGroups( $grantsFilter = null ) {
 134                 global $wgGrantPermissions, $wgGrantPermissionGroups;
 135
 136                 if ( is_array( $grantsFilter ) ) {
 137                         $grantsFilter = array_flip( $grantsFilter );
 138                 }
 139
 140                 $groups = [];
 141                 foreach ( $wgGrantPermissions as $grant => $rights ) {
 142                         if ( $grantsFilter !== null && !isset( $grantsFilter[$grant] ) ) {
 143                                 continue;
 144                         }
 145                         if ( isset( $wgGrantPermissionGroups[$grant] ) ) {
 146                                 $groups[$wgGrantPermissionGroups[$grant]][] = $grant;
 147                         } else {
 148                                 $groups['other'][] = $grant;
 149                         }
 150                 }
 151
 152                 return $groups;
 153         }
 154
 155         /**
 156          * Get the list of grants that are hidden and should always be granted
 157          * @return string[]
 158          */
 159         public static function getHiddenGrants() {
 160                 global $wgGrantPermissionGroups;
 161
 162                 $grants = [];
 163                 foreach ( $wgGrantPermissionGroups as $grant => $group ) {
 164                         if ( $group === 'hidden' ) {
 165                                 $grants[] = $grant;
 166                         }
 167                 }
 168                 return $grants;
 169         }
 170
 171         /**
 172          * Generate a link to Special:ListGrants for a particular grant name.
 173          *
 174          * This should be used to link end users to a full description of what
 175          * rights they are giving when they authorize a grant.
 176          *
 177          * @param string $grant the grant name
 178          * @param Language|string|null $lang
 179          * @return string (proto-relative) HTML link
 180          */
 181         public static function getGrantsLink( $grant, $lang = null ) {
 182                 $linkRenderer = MediaWikiServices::getInstance()->getLinkRenderer();
 183                 return $linkRenderer->makeKnownLink(
 184                         \SpecialPage::getTitleFor( 'Listgrants', false, $grant ),
 185                         self::grantName( $grant, $lang )
 186                 );
 187         }
 188
 189         /**
 190          * Generate wikitext to display a list of grants
 191          * @param string[]|null $grantsFilter If non-null, only display these grants.
 192          * @param Language|string|null $lang
 193          * @return string Wikitext
 194          */
 195         public static function getGrantsWikiText( $grantsFilter, $lang = null ) {
 196                 global $wgContLang;
 197
 198                 if ( is_string( $lang ) ) {
 199                         $lang = Language::factory( $lang );
 200                 } elseif ( $lang === null ) {
 201                         $lang = $wgContLang;
 202                 }
 203
 204                 $s = '';
 205                 foreach ( self::getGrantGroups( $grantsFilter ) as $group => $grants ) {
 206                         if ( $group === 'hidden' ) {
 207                                 continue; // implicitly granted
 208                         }
 209                         $s .= "*<span class=\"mw-grantgroup\">" .
 210                                 wfMessage( "grant-group-$group" )->inLanguage( $lang )->text() . "</span>\n";
 211                         $s .= ":" . $lang->semicolonList( self::grantNames( $grants, $lang ) ) . "\n";
 212                 }
 213                 return "$s\n";
 214         }
 215
 216 }