MediaWiki  master
UserDef.php
Go to the documentation of this file.
1 <?php
2 
4 
7 // phpcs:ignore MediaWiki.Classes.UnusedUseStatement.UnusedUse
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  return [
173  'interwiki',
174  is_string( $name ) ? $this->userFactory->newFromAnyId( 0, $value, null ) : null
175  ];
176  }
177 
178  // A valid user name?
179  $user = $this->userFactory->newFromName( $value, 'valid' );
180  if ( $user ) {
181  return [ 'name', $user ];
182  }
183 
184  // (T232672) Reproduce the normalization applied in User::getCanonicalName() when
185  // performing the checks below.
186  if ( strpos( $value, '#' ) !== false ) {
187  return [ '', null ];
188  }
189 
190  $t = $this->titleFactory->newFromText( $value );
191  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) { // likely
192  $t = $this->titleFactory->newFromText( "User:$value" );
193  }
194  if ( !$t || $t->getNamespace() !== NS_USER || $t->isExternal() ) {
195  // If it wasn't a valid User-namespace title, fail.
196  return [ '', null ];
197  }
198  $value = $t->getText();
199 
200  // An IP?
201  $b = IPUtils::RE_IP_BYTE;
202  if ( IPUtils::isValid( $value ) ||
203  // See comment for User::isIP. We don't just call that function
204  // here because it also returns true for things like
205  // 300.300.300.300 that are neither valid usernames nor valid IP
206  // addresses.
207  preg_match( "/^$b\.$b\.$b\.xxx$/D", $value )
208  ) {
209  return [ 'ip', $this->userFactory->newAnonymous( IPUtils::sanitizeIP( $value ) ) ];
210  }
211 
212  // A range?
213  if ( IPUtils::isValidRange( $value ) ) {
214  return [ 'cidr', $this->userFactory->newFromAnyId( 0, IPUtils::sanitizeIP( $value ), null ) ];
215  }
216 
217  // Fail.
218  return [ '', null ];
219  }
220 
221  public function getParamInfo( $name, array $settings, array $options ) {
222  $info = parent::getParamInfo( $name, $settings, $options );
223 
224  $info['subtypes'] = $settings[self::PARAM_ALLOWED_USER_TYPES];
225 
226  return $info;
227  }
228 
229  public function getHelpInfo( $name, array $settings, array $options ) {
230  $info = parent::getParamInfo( $name, $settings, $options );
231 
232  $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] );
233 
234  $subtypes = [];
235  foreach ( $settings[self::PARAM_ALLOWED_USER_TYPES] as $st ) {
236  // Messages: paramvalidator-help-type-user-subtype-name,
237  // paramvalidator-help-type-user-subtype-ip, paramvalidator-help-type-user-subtype-cidr,
238  // paramvalidator-help-type-user-subtype-interwiki, paramvalidator-help-type-user-subtype-id
239  $subtypes[] = MessageValue::new( "paramvalidator-help-type-user-subtype-$st" );
240  }
241  $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-user' )
242  ->params( $isMulti ? 2 : 1 )
243  ->textListParams( $subtypes )
244  ->numParams( count( $subtypes ) );
245 
246  return $info;
247  }
248 
249 }
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:229
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
MediaWiki\User\UserNameUtils\RIGOR_NONE
const RIGOR_NONE
Definition: UserNameUtils.php:53
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:29
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:32
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 Stable to override.
Definition: UserDef.php:93
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\$userFactory
UserFactory $userFactory
Definition: UserDef.php:57
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
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:33
Wikimedia\ParamValidator\ParamValidator::TypeDef\UserDef\getParamInfo
getParamInfo( $name, array $settings, array $options)
Describe parameter settings in a machine-readable format.
Definition: UserDef.php:221
Wikimedia\Message\MessageValue\new
static new( $key, $params=[])
Static constructor for easier chaining of ->params() methods.
Definition: MessageValue.php:42
NS_USER
const NS_USER
Definition: Defines.php:71
$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:137
MediaWiki\User\UserFactory
Creates User objects.
Definition: UserFactory.php:36
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