MediaWiki  master
UserDef.php
Go to the documentation of this file.
1 <?php
2 
4 
11 use TitleParser;
12 use Wikimedia\IPUtils;
17 
26 class UserDef extends TypeDef {
27 
44  public const PARAM_ALLOWED_USER_TYPES = 'param-allowed-user-types';
45 
55  public const PARAM_RETURN_OBJECT = 'param-return-object';
56 
59 
61  private $titleParser;
62 
64  private $userNameUtils;
65 
72  public function __construct(
74  UserIdentityLookup $userIdentityLookup,
76  UserNameUtils $userNameUtils
77  ) {
78  parent::__construct( $callbacks );
79  $this->userIdentityLookup = $userIdentityLookup;
80  $this->titleParser = $titleParser;
81  $this->userNameUtils = $userNameUtils;
82  }
83 
84  public function validate( $name, $value, array $settings, array $options ) {
85  list( $type, $user ) = $this->processUser( $value );
86 
87  if ( !$user || !in_array( $type, $settings[self::PARAM_ALLOWED_USER_TYPES], true ) ) {
88  $this->failure( 'baduser', $name, $value, $settings, $options );
89  }
90 
91  return empty( $settings[self::PARAM_RETURN_OBJECT] ) ? $user->getName() : $user;
92  }
93 
94  public function normalizeSettings( array $settings ) {
95  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
96  $settings[self::PARAM_ALLOWED_USER_TYPES] = array_values( array_intersect(
97  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ],
98  $settings[self::PARAM_ALLOWED_USER_TYPES]
99  ) );
100  }
101  if ( empty( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
102  $settings[self::PARAM_ALLOWED_USER_TYPES] = [ 'name', 'ip', 'cidr', 'interwiki' ];
103  }
104 
105  return parent::normalizeSettings( $settings );
106  }
107 
108  public function checkSettings( string $name, $settings, array $options, array $ret ): array {
109  $ret = parent::checkSettings( $name, $settings, $options, $ret );
110 
111  $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
112  self::PARAM_ALLOWED_USER_TYPES, self::PARAM_RETURN_OBJECT,
113  ] );
114 
115  if ( !is_bool( $settings[self::PARAM_RETURN_OBJECT] ?? false ) ) {
116  $ret['issues'][self::PARAM_RETURN_OBJECT] = 'PARAM_RETURN_OBJECT must be boolean, got '
117  . gettype( $settings[self::PARAM_RETURN_OBJECT] );
118  }
119 
120  $hasId = false;
121  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
122  if ( !is_array( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
123  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES must be an array, '
124  . 'got ' . gettype( $settings[self::PARAM_ALLOWED_USER_TYPES] );
125  } elseif ( $settings[self::PARAM_ALLOWED_USER_TYPES] === [] ) {
126  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES cannot be empty';
127  } else {
128  $bad = array_diff(
129  $settings[self::PARAM_ALLOWED_USER_TYPES],
130  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ]
131  );
132  if ( $bad ) {
133  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] =
134  'PARAM_ALLOWED_USER_TYPES contains invalid values: ' . implode( ', ', $bad );
135  }
136 
137  $hasId = in_array( 'id', $settings[self::PARAM_ALLOWED_USER_TYPES], true );
138  }
139  }
140 
141  if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) &&
142  ( $hasId || !empty( $settings[self::PARAM_RETURN_OBJECT] ) ) &&
143  (
144  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT1] ?? 100 ) > 10 ||
145  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT2] ?? 100 ) > 10
146  )
147  ) {
148  $ret['issues'][] = 'Multi-valued user-type parameters with PARAM_RETURN_OBJECT or allowing IDs '
149  . 'should set low values (<= 10) for PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2.'
150  . ' (Note that "<= 10" is arbitrary. If something hits this, we can investigate a real limit '
151  . 'once we have a real use case to look at.)';
152  }
153 
154  return $ret;
155  }
156 
163  private function processUser( string $value ): array {
164  // A user ID?
165  if ( preg_match( '/^#(\d+)$/D', $value, $m ) ) {
166  // This used to use the IP address of the current request if the
167  // id was 0, to match the behavior of User objects, but was switched
168  // to "Unknown user" because the former behavior is likely unexpected.
169  // If the id corresponds to a user in the database, use that user, otherwise
170  // return a UserIdentityValue with id 0 (regardless of the input id) and
171  // the name "Unknown user"
172  $userId = (int)$m[1];
173  if ( $userId !== 0 ) {
174  // Check the database.
175  $userIdentity = $this->userIdentityLookup->getUserIdentityByUserId( $userId );
176  if ( $userIdentity ) {
177  return [ 'id', $userIdentity ];
178  }
179  }
180  // Fall back to "Unknown user"
181  return [
182  'id',
183  new UserIdentityValue( 0, "Unknown user" )
184  ];
185  }
186 
187  // An interwiki username?
188  if ( ExternalUserNames::isExternal( $value ) ) {
189  $name = $this->userNameUtils->getCanonical( $value, UserNameUtils::RIGOR_NONE );
190  // UserIdentityValue has the username which includes the > separating the external
191  // wiki database and the actual name, but is created for the *local* wiki, like
192  // for User objects (local is the default, but we specify it anyway to show
193  // that its intentional even though the username is for a different wiki)
194  // NOTE: We deliberately use the raw $value instead of the canonical $name
195  // to avoid convering the first character of the interwiki prefic to uppercase
196  $user = is_string( $name ) ? new UserIdentityValue( 0, $value, UserIdentityValue::LOCAL ) : null;
197  return [ 'interwiki', $user ];
198  }
199 
200  // A valid user name?
201  // Match behavior of UserFactory::newFromName with RIGOR_VALID and User::getId()
202  // we know that if there is a canonical form from UserNameUtils then this can't
203  // look like an IP, and since we checked for external user names above it isn't
204  // that either, so if this is a valid user name then we check the database for
205  // the id, and if there is no user with this name the id is 0
206  $canonicalName = $this->userNameUtils->getCanonical( $value, UserNameUtils::RIGOR_VALID );
207  if ( $canonicalName ) {
208  $userIdentity = $this->userIdentityLookup->getUserIdentityByName( $canonicalName );
209  if ( $userIdentity ) {
210  return [ 'name', $userIdentity ];
211  }
212  // Fall back to id 0
213  return [
214  'name',
215  new UserIdentityValue( 0, $canonicalName )
216  ];
217  }
218 
219  // (T232672) Reproduce the normalization applied in UserNameUtils::getCanonical() when
220  // performing the checks below.
221  if ( strpos( $value, '#' ) !== false ) {
222  return [ '', null ];
223  }
224 
225  try {
226  $t = $this->titleParser->parseTitle( $value );
227  } catch ( MalformedTitleException $_ ) {
228  $t = null;
229  }
230  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) { // likely
231  try {
232  $t = $this->titleParser->parseTitle( "User:$value" );
233  } catch ( MalformedTitleException $_ ) {
234  $t = null;
235  }
236  }
237  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) {
238  // If it wasn't a valid User-namespace title, fail.
239  return [ '', null ];
240  }
241  $value = $t->getText();
242 
243  // An IP?
244  $b = IPUtils::RE_IP_BYTE;
245  if ( IPUtils::isValid( $value ) ||
246  // See comment for UserNameUtils::isIP. We don't just call that function
247  // here because it also returns true for things like
248  // 300.300.300.300 that are neither valid usernames nor valid IP
249  // addresses.
250  preg_match( "/^$b\.$b\.$b\.xxx$/D", $value )
251  ) {
252  $name = IPUtils::sanitizeIP( $value );
253  // We don't really need to use UserNameUtils::getCanonical() because for anonymous
254  // users the only validation is that there is no `#` (which is already the case if its
255  // a valid IP or matches the regex) and the only normalization is making the first
256  // character uppercase (doesn't matter for numbers) and replacing underscores with
257  // spaces (doesn't apply to IPs). But, better safe than sorry?
258  $name = $this->userNameUtils->getCanonical( $name, UserNameUtils::RIGOR_NONE );
259  return [ 'ip', UserIdentityValue::newAnonymous( $name ) ];
260  }
261 
262  // A range?
263  if ( IPUtils::isValidRange( $value ) ) {
264  $name = IPUtils::sanitizeIP( $value );
265  // Per above, the UserNameUtils call isn't strictly needed, but doesn't hurt
266  $name = $this->userNameUtils->getCanonical( $name, UserNameUtils::RIGOR_NONE );
267  return [ 'cidr', UserIdentityValue::newAnonymous( $name ) ];
268  }
269 
270  // Fail.
271  return [ '', null ];
272  }
273 
274  public function getParamInfo( $name, array $settings, array $options ) {
275  $info = parent::getParamInfo( $name, $settings, $options );
276 
277  $info['subtypes'] = $settings[self::PARAM_ALLOWED_USER_TYPES];
278 
279  return $info;
280  }
281 
282  public function getHelpInfo( $name, array $settings, array $options ) {
283  $info = parent::getParamInfo( $name, $settings, $options );
284 
285  $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
286 
287  $subtypes = [];
288  foreach ( $settings[self::PARAM_ALLOWED_USER_TYPES] as $st ) {
289  // Messages: paramvalidator-help-type-user-subtype-name,
290  // paramvalidator-help-type-user-subtype-ip, paramvalidator-help-type-user-subtype-cidr,
291  // paramvalidator-help-type-user-subtype-interwiki, paramvalidator-help-type-user-subtype-id
292  $subtypes[] = MessageValue::new( "paramvalidator-help-type-user-subtype-$st" );
293  }
294  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-user' )
295  ->params( $isMulti ? 2 : 1 )
296  ->textListParams( $subtypes )
297  ->numParams( count( $subtypes ) );
298 
299  return $info;
300  }
301 
302 }
MediaWiki\User\UserIdentityValue
Value object representing a user's identity.
Definition: UserIdentityValue.php:35
Wikimedia\ParamValidator\Callbacks
Interface defining callbacks needed by ParamValidator.
Definition: Callbacks.php:21
Wikimedia\ParamValidator\TypeDef\failure
failure( $failure, $name, $value, array $settings, array $options, $fatal=true)
Record a failure message.
Definition: TypeDef.php:49
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\getHelpInfo
getHelpInfo( $name, array $settings, array $options)
Describe parameter settings in human-readable format.
Definition: UserDef.php:282
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:108
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$userIdentityLookup
UserIdentityLookup $userIdentityLookup
Definition: UserDef.php:58
ExternalUserNames
Class to parse and build external user names.
Definition: ExternalUserNames.php:30
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\PARAM_ALLOWED_USER_TYPES
const PARAM_ALLOWED_USER_TYPES
(string[]) Allowed types of user.
Definition: UserDef.php:44
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$titleParser
TitleParser $titleParser
Definition: UserDef.php:61
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\validate
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: UserDef.php:84
MediaWiki\User\UserIdentity
Interface for objects representing user identity.
Definition: UserIdentity.php:39
Wikimedia\Message\MessageValue
Value object representing a message for i18n.
Definition: MessageValue.php:16
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef
Type definition for user types.
Definition: UserDef.php:26
Wikimedia\ParamValidator\TypeDef
Base definition for ParamValidator types.
Definition: TypeDef.php:19
MediaWiki\ParamValidator\TypeDef
Definition: NamespaceDef.php:3
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\normalizeSettings
normalizeSettings(array $settings)
Normalize a settings array.
Definition: UserDef.php:94
TitleParser
A title parser service for MediaWiki.
Definition: TitleParser.php:33
MediaWiki\User\UserIdentityValue\newAnonymous
static newAnonymous(string $name, $wikiId=self::LOCAL)
Create UserIdentity for an anonymous user.
Definition: UserIdentityValue.php:92
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\PARAM_RETURN_OBJECT
const PARAM_RETURN_OBJECT
(bool) Whether to return a UserIdentity object.
Definition: UserDef.php:55
MediaWiki\User\UserIdentityLookup
Definition: UserIdentityLookup.php:33
Wikimedia\ParamValidator\ParamValidator\PARAM_ISMULTI
const PARAM_ISMULTI
(bool) Indicate that the parameter is multi-valued.
Definition: ParamValidator.php:112
NS_USER
const NS_USER
Definition: Defines.php:66
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$userNameUtils
UserNameUtils $userNameUtils
Definition: UserDef.php:64
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\processUser
processUser(string $value)
Process $value to a UserIdentity, if possible.
Definition: UserDef.php:163
MalformedTitleException
MalformedTitleException is thrown when a TitleParser is unable to parse a title string.
Definition: MalformedTitleException.php:26
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
MediaWiki\User\UserNameUtils
UserNameUtils service.
Definition: UserNameUtils.php:42
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:274
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:42
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\__construct
__construct(Callbacks $callbacks, UserIdentityLookup $userIdentityLookup, TitleParser $titleParser, UserNameUtils $userNameUtils)
Definition: UserDef.php:72
$t
$t
Definition: testCompression.php:74
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:149
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42
Wikimedia\ParamValidator\TypeDef\$callbacks
Callbacks $callbacks
Definition: TypeDef.php:22
$type
$type
Definition: testCompression.php:52