MediaWiki  master
UserDef.php
Go to the documentation of this file.
1 <?php
2 
4 
10 use TitleFactory;
11 use Wikimedia\IPUtils;
16 
25 class UserDef extends TypeDef {
26 
43  public const PARAM_ALLOWED_USER_TYPES = 'param-allowed-user-types';
44 
54  public const PARAM_RETURN_OBJECT = 'param-return-object';
55 
57  private $userFactory;
58 
60  private $titleFactory;
61 
63  private $userNameUtils;
64 
71  public function __construct(
73  UserFactory $userFactory,
75  UserNameUtils $userNameUtils
76  ) {
77  parent::__construct( $callbacks );
78  $this->userFactory = $userFactory;
79  $this->titleFactory = $titleFactory;
80  $this->userNameUtils = $userNameUtils;
81  }
82 
83  public function validate( $name, $value, array $settings, array $options ) {
84  list( $type, $user ) = $this->processUser( $value );
85 
86  if ( !$user || !in_array( $type, $settings[self::PARAM_ALLOWED_USER_TYPES], true ) ) {
87  $this->failure( 'baduser', $name, $value, $settings, $options );
88  }
89 
90  return empty( $settings[self::PARAM_RETURN_OBJECT] ) ? $user->getName() : $user;
91  }
92 
93  public function normalizeSettings( array $settings ) {
94  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
95  $settings[self::PARAM_ALLOWED_USER_TYPES] = array_values( array_intersect(
96  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ],
97  $settings[self::PARAM_ALLOWED_USER_TYPES]
98  ) );
99  }
100  if ( empty( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
101  $settings[self::PARAM_ALLOWED_USER_TYPES] = [ 'name', 'ip', 'cidr', 'interwiki' ];
102  }
103 
104  return parent::normalizeSettings( $settings );
105  }
106 
107  public function checkSettings( string $name, $settings, array $options, array $ret ): array {
108  $ret = parent::checkSettings( $name, $settings, $options, $ret );
109 
110  $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [
111  self::PARAM_ALLOWED_USER_TYPES, self::PARAM_RETURN_OBJECT,
112  ] );
113 
114  if ( !is_bool( $settings[self::PARAM_RETURN_OBJECT] ?? false ) ) {
115  $ret['issues'][self::PARAM_RETURN_OBJECT] = 'PARAM_RETURN_OBJECT must be boolean, got '
116  . gettype( $settings[self::PARAM_RETURN_OBJECT] );
117  }
118 
119  $hasId = false;
120  if ( isset( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
121  if ( !is_array( $settings[self::PARAM_ALLOWED_USER_TYPES] ) ) {
122  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES must be an array, '
123  . 'got ' . gettype( $settings[self::PARAM_ALLOWED_USER_TYPES] );
124  } elseif ( $settings[self::PARAM_ALLOWED_USER_TYPES] === [] ) {
125  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] = 'PARAM_ALLOWED_USER_TYPES cannot be empty';
126  } else {
127  $bad = array_diff(
128  $settings[self::PARAM_ALLOWED_USER_TYPES],
129  [ 'name', 'ip', 'cidr', 'interwiki', 'id' ]
130  );
131  if ( $bad ) {
132  $ret['issues'][self::PARAM_ALLOWED_USER_TYPES] =
133  'PARAM_ALLOWED_USER_TYPES contains invalid values: ' . implode( ', ', $bad );
134  }
135 
136  $hasId = in_array( 'id', $settings[self::PARAM_ALLOWED_USER_TYPES], true );
137  }
138  }
139 
140  if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) &&
141  ( $hasId || !empty( $settings[self::PARAM_RETURN_OBJECT] ) ) &&
142  (
143  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT1] ?? 100 ) > 10 ||
144  ( $settings[ParamValidator::PARAM_ISMULTI_LIMIT2] ?? 100 ) > 10
145  )
146  ) {
147  $ret['issues'][] = 'Multi-valued user-type parameters with PARAM_RETURN_OBJECT or allowing IDs '
148  . 'should set low values (<= 10) for PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2.'
149  . ' (Note that "<= 10" is arbitrary. If something hits this, we can investigate a real limit '
150  . 'once we have a real use case to look at.)';
151  }
152 
153  return $ret;
154  }
155 
162  private function processUser( string $value ): array {
163  // A user ID?
164  if ( preg_match( '/^#(\d+)$/D', $value, $m ) ) {
165  return [ 'id', $this->userFactory->newFromId( $m[1] ) ];
166 
167  }
168 
169  // An interwiki username?
170  if ( ExternalUserNames::isExternal( $value ) ) {
171  $name = $this->userNameUtils->getCanonical( $value, UserNameUtils::RIGOR_NONE );
172  // UserIdentityValue has the username which includes the > separating the external
173  // wiki database and the actual name, but is created for the *local* wiki, like
174  // for User objects (local is the default, but we specify it anyway to show
175  // that its intentional even though the username is for a different wiki)
176  // NOTE: We deliberately use the raw $value instead of the canonical $name
177  // to avoid convering the first character of the interwiki prefic to uppercase
178  $user = is_string( $name ) ? new UserIdentityValue( 0, $value, UserIdentityValue::LOCAL ) : null;
179  return [ 'interwiki', $user ];
180  }
181 
182  // A valid user name?
183  $user = $this->userFactory->newFromName( $value, UserFactory::RIGOR_VALID );
184  if ( $user ) {
185  return [ 'name', $user ];
186  }
187 
188  // (T232672) Reproduce the normalization applied in UserNameUtils::getCanonical() when
189  // performing the checks below.
190  if ( strpos( $value, '#' ) !== false ) {
191  return [ '', null ];
192  }
193 
194  $t = $this->titleFactory->newFromText( $value );
195  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) { // likely
196  $t = $this->titleFactory->newFromText( "User:$value" );
197  }
198  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) {
199  // If it wasn't a valid User-namespace title, fail.
200  return [ '', null ];
201  }
202  $value = $t->getText();
203 
204  // An IP?
205  $b = IPUtils::RE_IP_BYTE;
206  if ( IPUtils::isValid( $value ) ||
207  // See comment for UserNameUtils::isIP. We don't just call that function
208  // here because it also returns true for things like
209  // 300.300.300.300 that are neither valid usernames nor valid IP
210  // addresses.
211  preg_match( "/^$b\.$b\.$b\.xxx$/D", $value )
212  ) {
213  $name = IPUtils::sanitizeIP( $value );
214  // We don't really need to use UserNameUtils::getCanonical() because for anonymous
215  // users the only validation is that there is no `#` (which is already the case if its
216  // a valid IP or matches the regex) and the only normalization is making the first
217  // character uppercase (doesn't matter for numbers) and replacing underscores with
218  // spaces (doesn't apply to IPs). But, better safe than sorry?
219  $name = $this->userNameUtils->getCanonical( $name, UserNameUtils::RIGOR_NONE );
220  return [ 'ip', UserIdentityValue::newAnonymous( $name ) ];
221  }
222 
223  // A range?
224  if ( IPUtils::isValidRange( $value ) ) {
225  $name = IPUtils::sanitizeIP( $value );
226  // Per above, the UserNameUtils call isn't strictly needed, but doesn't hurt
227  $name = $this->userNameUtils->getCanonical( $name, UserNameUtils::RIGOR_NONE );
228  return [ 'cidr', UserIdentityValue::newAnonymous( $name ) ];
229  }
230 
231  // Fail.
232  return [ '', null ];
233  }
234 
235  public function getParamInfo( $name, array $settings, array $options ) {
236  $info = parent::getParamInfo( $name, $settings, $options );
237 
238  $info['subtypes'] = $settings[self::PARAM_ALLOWED_USER_TYPES];
239 
240  return $info;
241  }
242 
243  public function getHelpInfo( $name, array $settings, array $options ) {
244  $info = parent::getParamInfo( $name, $settings, $options );
245 
246  $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
247 
248  $subtypes = [];
249  foreach ( $settings[self::PARAM_ALLOWED_USER_TYPES] as $st ) {
250  // Messages: paramvalidator-help-type-user-subtype-name,
251  // paramvalidator-help-type-user-subtype-ip, paramvalidator-help-type-user-subtype-cidr,
252  // paramvalidator-help-type-user-subtype-interwiki, paramvalidator-help-type-user-subtype-id
253  $subtypes[] = MessageValue::new( "paramvalidator-help-type-user-subtype-$st" );
254  }
255  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-user' )
256  ->params( $isMulti ? 2 : 1 )
257  ->textListParams( $subtypes )
258  ->numParams( count( $subtypes ) );
259 
260  return $info;
261  }
262 
263 }
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:243
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$titleFactory
TitleFactory $titleFactory
Definition: UserDef.php:60
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:107
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:43
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\validate
validate( $name, $value, array $settings, array $options)
Validate the value.
Definition: UserDef.php:83
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:25
Wikimedia\ParamValidator\TypeDef
Base definition for ParamValidator types.
Definition: TypeDef.php:19
MediaWiki\ParamValidator\TypeDef
Definition: NamespaceDef.php:3
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\__construct
__construct(Callbacks $callbacks, UserFactory $userFactory, TitleFactory $titleFactory, UserNameUtils $userNameUtils)
Definition: UserDef.php:71
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\normalizeSettings
normalizeSettings(array $settings)
Normalize a settings array.
Definition: UserDef.php:93
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$userFactory
UserFactory $userFactory
Definition: UserDef.php:57
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:54
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
NS_USER
const NS_USER
Definition: Defines.php:66
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$userNameUtils
UserNameUtils $userNameUtils
Definition: UserDef.php:63
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\processUser
processUser(string $value)
Process $value to a UserIdentity, if possible.
Definition: UserDef.php:162
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
TitleFactory
Creates Title objects.
Definition: TitleFactory.php:35
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\getParamInfo
getParamInfo( $name, array $settings, array $options)
Describe parameter settings in a machine-readable format.
Definition: UserDef.php:235
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:42
$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
MediaWiki\User\UserFactory
Creates User objects.
Definition: UserFactory.php:41
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