MediaWiki  master
UserDef.php
Go to the documentation of this file.
1 <?php
2 
4 
6 // phpcs:ignore MediaWiki.Classes.UnusedUseStatement.UnusedUse
8 use Title;
9 use User;
10 use Wikimedia\IPUtils;
14 
23 class UserDef extends TypeDef {
24 
41  public const PARAM_ALLOWED_USER_TYPES = 'param-allowed-user-types';
42 
52  public const PARAM_RETURN_OBJECT = 'param-return-object';
53 
54  public function validate( $name, $value, array $settings, array $options ) {
55  list( $type, $user ) = $this->processUser( $value );
56 
57  if ( !$user || !in_array( $type, $settings[self::PARAM_ALLOWED_USER_TYPES], true ) ) {
58  $this->failure( 'baduser', $name, $value, $settings, $options );
59  }
60  return empty( $settings[self::PARAM_RETURN_OBJECT] ) ? $user->getName() : $user;
61  }
62 
63  public function normalizeSettings( array $settings ) {
64  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
65  $settings[self::PARAM_ALLOWED_USER_TYPES] = array_values( array_intersect(
66  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ],
67  $settings[self::PARAM_ALLOWED_USER_TYPES]
68  ) );
69  }
70  if ( empty( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
71  $settings[self::PARAM_ALLOWED_USER_TYPES] = [ 'name', 'ip', 'cidr', 'interwiki' ];
72  }
73 
74  return parent::normalizeSettings( $settings );
75  }
76 
77  public function checkSettings( string $name, $settings, array $options, array $ret ) : array {
78  $ret = parent::checkSettings( $name, $settings, $options, $ret );
79 
80  $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
81  self::PARAM_ALLOWED_USER_TYPES, self::PARAM_RETURN_OBJECT,
82  ] );
83 
84  if ( !is_bool( $settings[self::PARAM_RETURN_OBJECT] ?? false ) ) {
85  $ret['issues'][self::PARAM_RETURN_OBJECT] = 'PARAM_RETURN_OBJECT must be boolean, got '
86  . gettype( $settings[self::PARAM_RETURN_OBJECT] );
87  }
88 
89  $hasId = false;
90  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
91  if ( !is_array( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
92  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES must be an array, '
93  . 'got ' . gettype( $settings[self::PARAM_ALLOWED_USER_TYPES] );
94  } elseif ( $settings[self::PARAM_ALLOWED_USER_TYPES] === [] ) {
95  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES cannot be empty';
96  } else {
97  $bad = array_diff(
98  $settings[self::PARAM_ALLOWED_USER_TYPES],
99  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ]
100  );
101  if ( $bad ) {
102  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] =
103  'PARAM_ALLOWED_USER_TYPES contains invalid values: ' . implode( ', ', $bad );
104  }
105 
106  $hasId = in_array( 'id', $settings[self::PARAM_ALLOWED_USER_TYPES], true );
107  }
108  }
109 
110  if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) &&
111  ( $hasId || !empty( $settings[self::PARAM_RETURN_OBJECT] ) ) &&
112  (
113  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT1] ?? 100 ) > 10 ||
114  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT2] ?? 100 ) > 10
115  )
116  ) {
117  $ret['issues'][] = 'Multi-valued user-type parameters with PARAM_RETURN_OBJECT or allowing IDs '
118  . 'should set low values (<= 10) for PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2.'
119  . ' (Note that "<= 10" is arbitrary. If something hits this, we can investigate a real limit '
120  . 'once we have a real use case to look at.)';
121  }
122 
123  return $ret;
124  }
125 
132  private function processUser( string $value ) : array {
133  // A user ID?
134  if ( preg_match( '/^#(\d+)$/D', $value, $m ) ) {
135  return [ 'id', User::newFromId( $m[1] ) ];
136  }
137 
138  // An interwiki username?
139  if ( ExternalUserNames::isExternal( $value ) ) {
140  $name = User::getCanonicalName( $value, false );
141  return [
142  'interwiki',
143  is_string( $name ) ? User::newFromAnyId( 0, $value, null ) : null
144  ];
145  }
146 
147  // A valid user name?
148  $user = User::newFromName( $value, 'valid' );
149  if ( $user ) {
150  return [ 'name', $user ];
151  }
152 
153  // (T232672) Reproduce the normalization applied in User::getCanonicalName() when
154  // performing the checks below.
155  if ( strpos( $value, '#' ) !== false ) {
156  return [ '', null ];
157  }
158  $t = Title::newFromText( $value ); // In case of explicit "User:" prefix, sigh.
159  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) { // likely
160  $t = Title::newFromText( "User:$value" );
161  }
162  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) {
163  // If it wasn't a valid User-namespace title, fail.
164  return [ '', null ];
165  }
166  $value = $t->getText();
167 
168  // An IP?
169  $b = IPUtils::RE_IP_BYTE;
170  if ( IPUtils::isValid( $value ) ||
171  // See comment for User::isIP. We don't just call that function
172  // here because it also returns true for things like
173  // 300.300.300.300 that are neither valid usernames nor valid IP
174  // addresses.
175  preg_match( "/^$b\.$b\.$b\.xxx$/D", $value )
176  ) {
177  return [ 'ip', User::newFromAnyId( 0, IPUtils::sanitizeIP( $value ), null ) ];
178  }
179 
180  // A range?
181  if ( IPUtils::isValidRange( $value ) ) {
182  return [ 'cidr', User::newFromAnyId( 0, IPUtils::sanitizeIP( $value ), null ) ];
183  }
184 
185  // Fail.
186  return [ '', null ];
187  }
188 
189  public function getParamInfo( $name, array $settings, array $options ) {
190  $info = parent::getParamInfo( $name, $settings, $options );
191 
192  $info['subtypes'] = $settings[self::PARAM_ALLOWED_USER_TYPES];
193 
194  return $info;
195  }
196 
197  public function getHelpInfo( $name, array $settings, array $options ) {
198  $info = parent::getParamInfo( $name, $settings, $options );
199 
200  $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
201 
202  $subtypes = [];
203  foreach ( $settings[self::PARAM_ALLOWED_USER_TYPES] as $st ) {
204  // Messages: paramvalidator-help-type-user-subtype-name,
205  // paramvalidator-help-type-user-subtype-ip, paramvalidator-help-type-user-subtype-cidr,
206  // paramvalidator-help-type-user-subtype-interwiki, paramvalidator-help-type-user-subtype-id
207  $subtypes[] = MessageValue::new( "paramvalidator-help-type-user-subtype-$st" );
208  }
209  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-user' )
210  ->params( $isMulti ? 2 : 1 )
211  ->textListParams( $subtypes )
212  ->numParams( count( $subtypes ) );
213 
214  return $info;
215  }
216 
217 }
User\newFromId
static newFromId( $id)
Static factory method for creation from a given user ID.
Definition: User.php:557
Title\newFromText
static newFromText( $text, $defaultNamespace=NS_MAIN)
Create a new Title from text, such as what one would find in a link.
Definition: Title.php:332
Wikimedia\ParamValidator\TypeDef\failure
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition: TypeDef.php:43
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\getHelpInfo
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
Definition: UserDef.php:197
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT1
const PARAM_ISMULTI_LIMIT1
(int) Maximum number of multi-valued parameter values allowed
Definition: ParamValidator.php:119
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\checkSettings
checkSettings(string $name, $settings, array $options, array $ret)
Validate a parameter settings array.
Definition: UserDef.php:77
ExternalUserNames
Class to parse and build external user names.
Definition: ExternalUserNames.php:29
User\newFromName
static newFromName( $name, $validate='valid')
Static factory method for creation from username.
Definition: User.php:533
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\PARAM_ALLOWED_USER_TYPES
const PARAM_ALLOWED_USER_TYPES
(string[]) Allowed types of user.
Definition: UserDef.php:41
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\validate
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: UserDef.php:54
MediaWiki\User\UserIdentity
Interface for objects representing user identity.
Definition: UserIdentity.php:32
Wikimedia\Message\MessageValue
Value object representing a message for i18n.
Definition: MessageValue.php:14
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef
Type definition for user types.
Definition: UserDef.php:23
Wikimedia\ParamValidator\TypeDef
Base definition for ParamValidator types.
Definition: TypeDef.php:18
MediaWiki\ParamValidator\TypeDef
Definition: NamespaceDef.php:3
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\normalizeSettings
normalizeSettings(array $settings)
Normalize a settings array.
Definition: UserDef.php:63
User\newFromAnyId
static newFromAnyId( $userId, $userName, $actorId, $dbDomain=false)
Static factory method for creation from an ID, name, and/or actor ID.
Definition: User.php:614
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\PARAM_RETURN_OBJECT
const PARAM_RETURN_OBJECT
(bool) Whether to return a UserIdentity object.
Definition: UserDef.php:52
RE_IP_BYTE
const RE_IP_BYTE
An IPv4 address is made of 4 bytes from x00 to xFF which is d0 to d255.
Definition: IP.php:27
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
Definition: ParamValidator.php:112
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\processUser
processUser(string $value)
Process $value to a UserIdentity, if possible.
Definition: UserDef.php:132
Title
Represents a title within MediaWiki.
Definition: Title.php:42
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI_LIMIT2
const PARAM_ISMULTI_LIMIT2
(int) Maximum number of multi-valued parameter values allowed for users allowed high limits.
Definition: ParamValidator.php:127
User\getCanonicalName
static getCanonicalName( $name, $validate='valid')
Given unvalidated user input, return a canonical username, or false if the username is invalid.
Definition: User.php:1125
Wikimedia\ParamValidator\TypeDef
Definition: BooleanDef.php:3
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\getParamInfo
getParamInfo( $name, array $settings, array $options)
Describe parameter settings in a machine-readable format.
Definition: UserDef.php:189
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:38
NS_USER
const NS_USER
Definition: Defines.php:71
$t
$t
Definition: testCompression.php:74
User
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:54
Wikimedia\ParamValidator\ParamValidator\PARAM_TYPE
const PARAM_TYPE
(string|array) Type of the parameter.
Definition: ParamValidator.php:76
ExternalUserNames\isExternal
static isExternal( $username)
Tells whether the username is external or not.
Definition: ExternalUserNames.php:137
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42
$type
$type
Definition: testCompression.php:52