includes/MWGrants.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  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-editsiteconfig, grant-editpage, grant-editprotected,
  62                 // grant-highvolume, grant-oversight, grant-patrol, grant-protect,
  63                 // grant-rollback, grant-sendemail, grant-uploadeditmovefile,
  64                 // grant-uploadfile, grant-basic, grant-viewdeleted,
  65                 // grant-viewmywatchlist, 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 && is_string( $lang ) ) {
  90                         $lang = Language::factory( $lang );
  91                 }
  92
  93                 $ret = [];
  94                 foreach ( $grants as $grant ) {
  95                         $ret[] = self::grantName( $grant, $lang );
  96                 }
  97                 return $ret;
  98         }
  99
 100         /**
 101          * Fetch the rights allowed by a set of grants.
 102          * @param string[]|string $grants
 103          * @return string[]
 104          */
 105         public static function getGrantRights( $grants ) {
 106                 global $wgGrantPermissions;
 107
 108                 $rights = [];
 109                 foreach ( (array)$grants as $grant ) {
 110                         if ( isset( $wgGrantPermissions[$grant] ) ) {
 111                                 $rights = array_merge( $rights, array_keys( array_filter( $wgGrantPermissions[$grant] ) ) );
 112                         }
 113                 }
 114                 return array_unique( $rights );
 115         }
 116
 117         /**
 118          * Test that all grants in the list are known.
 119          * @param string[] $grants
 120          * @return bool
 121          */
 122         public static function grantsAreValid( array $grants ) {
 123                 return array_diff( $grants, self::getValidGrants() ) === [];
 124         }
 125
 126         /**
 127          * Divide the grants into groups.
 128          * @param string[]|null $grantsFilter
 129          * @return array Map of (group => (grant list))
 130          */
 131         public static function getGrantGroups( $grantsFilter = null ) {
 132                 global $wgGrantPermissions, $wgGrantPermissionGroups;
 133
 134                 if ( is_array( $grantsFilter ) ) {
 135                         $grantsFilter = array_flip( $grantsFilter );
 136                 }
 137
 138                 $groups = [];
 139                 foreach ( $wgGrantPermissions as $grant => $rights ) {
 140                         if ( $grantsFilter !== null && !isset( $grantsFilter[$grant] ) ) {
 141                                 continue;
 142                         }
 143                         if ( isset( $wgGrantPermissionGroups[$grant] ) ) {
 144                                 $groups[$wgGrantPermissionGroups[$grant]][] = $grant;
 145                         } else {
 146                                 $groups['other'][] = $grant;
 147                         }
 148                 }
 149
 150                 return $groups;
 151         }
 152
 153         /**
 154          * Get the list of grants that are hidden and should always be granted
 155          * @return string[]
 156          */
 157         public static function getHiddenGrants() {
 158                 global $wgGrantPermissionGroups;
 159
 160                 $grants = [];
 161                 foreach ( $wgGrantPermissionGroups as $grant => $group ) {
 162                         if ( $group === 'hidden' ) {
 163                                 $grants[] = $grant;
 164                         }
 165                 }
 166                 return $grants;
 167         }
 168
 169         /**
 170          * Generate a link to Special:ListGrants for a particular grant name.
 171          *
 172          * This should be used to link end users to a full description of what
 173          * rights they are giving when they authorize a grant.
 174          *
 175          * @param string $grant the grant name
 176          * @param Language|string|null $lang
 177          * @return string (proto-relative) HTML link
 178          */
 179         public static function getGrantsLink( $grant, $lang = null ) {
 180                 $linkRenderer = MediaWikiServices::getInstance()->getLinkRenderer();
 181                 return $linkRenderer->makeKnownLink(
 182                         \SpecialPage::getTitleFor( 'Listgrants', false, $grant ),
 183                         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                 if ( is_string( $lang ) ) {
 195                         $lang = Language::factory( $lang );
 196                 } elseif ( $lang === null ) {
 197                         $lang = MediaWikiServices::getInstance()->getContentLanguage();
 198                 }
 199
 200                 $s = '';
 201                 foreach ( self::getGrantGroups( $grantsFilter ) as $group => $grants ) {
 202                         if ( $group === 'hidden' ) {
 203                                 continue; // implicitly granted
 204                         }
 205                         $s .= "*<span class=\"mw-grantgroup\">" .
 206                                 wfMessage( "grant-group-$group" )->inLanguage( $lang )->text() . "</span>\n";
 207                         $s .= ":" . $lang->semicolonList( self::grantNames( $grants, $lang ) ) . "\n";
 208                 }
 209                 return "$s\n";
 210         }
 211
 212 }