MediaWiki master
userOptions.php
Go to the documentation of this file.
1<?php
32
33// @codeCoverageIgnoreStart
34require_once __DIR__ . '/Maintenance.php';
35// @codeCoverageIgnoreEnd
36
41
42 public function __construct() {
43 parent::__construct();
44
45 $this->addDescription( 'Pass through all users and change or delete one of their options.
46The new option is NOT validated.' );
47
48 $this->addOption( 'list', 'List available user options and their default value' );
49 $this->addOption( 'usage', 'Report all options statistics or just one if you specify it' );
50 $this->addOption(
51 'old',
52 'The value to look for. If it is a default value for the option, pass --old-is-default as well.',
53 false, true, false, true
54 );
55 $this->addOption( 'old-is-default', 'If passed, --old is interpreted as a default value.' );
56 $this->addOption( 'new', 'New value to update users with', false, true );
57 $this->addOption( 'delete', 'Delete the option instead of updating' );
58 $this->addOption( 'delete-defaults', 'Delete user_properties row matching the default' );
59 $this->addOption( 'fromuserid', 'Start from this user ID when changing/deleting options',
60 false, true );
61 $this->addOption( 'touserid', 'Do not go beyond this user ID when changing/deleting options',
62 false, true );
63 $this->addOption( 'nowarn', 'Hides the 5 seconds warning' );
64 $this->addOption( 'dry', 'Do not save user settings back to database' );
65 $this->addArg( 'option name', 'Name of the option to change or provide statistics about', false );
66 $this->setBatchSize( 100 );
67 }
68
72 public function execute() {
73 if ( $this->hasOption( 'list' ) ) {
74 $this->listAvailableOptions();
75 } elseif ( $this->hasOption( 'usage' ) ) {
76 $this->showUsageStats();
77 } elseif ( $this->hasOption( 'old' )
78 && $this->hasOption( 'new' )
79 && $this->hasArg( 0 )
80 ) {
81 $this->updateOptions();
82 } elseif ( $this->hasOption( 'delete' ) ) {
83 $this->deleteOptions();
84 } elseif ( $this->hasOption( 'delete-defaults' ) ) {
85 $this->deleteDefaults();
86 } else {
87 $this->maybeHelp( true );
88 }
89 }
90
94 private function listAvailableOptions() {
95 $userOptionsLookup = $this->getServiceContainer()->getUserOptionsLookup();
96 $def = $userOptionsLookup->getDefaultOptions( null );
97 ksort( $def );
98 $maxOpt = 0;
99 foreach ( $def as $opt => $value ) {
100 $maxOpt = max( $maxOpt, strlen( $opt ) );
101 }
102 foreach ( $def as $opt => $value ) {
103 $this->output( sprintf( "%-{$maxOpt}s: %s\n", $opt, $value ) );
104 }
105 }
106
110 private function showUsageStats() {
111 $option = $this->getArg( 0 );
112
113 $ret = [];
114 $userOptionsLookup = $this->getServiceContainer()->getUserOptionsLookup();
115 $defaultOptions = $userOptionsLookup->getDefaultOptions();
116
117 if ( $option && !array_key_exists( $option, $defaultOptions ) ) {
118 $this->fatalError( "Invalid user option. Use --list to see valid choices\n" );
119 }
120
121 // We list user by user_id from one of the replica DBs
122 $dbr = $this->getServiceContainer()->getConnectionProvider()->getReplicaDatabase();
123
124 $result = $dbr->newSelectQueryBuilder()
125 ->select( [ 'user_id' ] )
126 ->from( 'user' )
127 ->caller( __METHOD__ )->fetchResultSet();
128
129 foreach ( $result as $id ) {
130 $user = User::newFromId( $id->user_id );
131
132 // Get the options and update stats
133 if ( $option ) {
134 $userValue = $userOptionsLookup->getOption( $user, $option );
135 if ( $userValue != $defaultOptions[$option] ) {
136 $ret[$option][$userValue] = ( $ret[$option][$userValue] ?? 0 ) + 1;
137 }
138 } else {
139 foreach ( $defaultOptions as $name => $defaultValue ) {
140 $userValue = $userOptionsLookup->getOption( $user, $name );
141 if ( $userValue != $defaultValue ) {
142 $ret[$name][$userValue] = ( $ret[$name][$userValue] ?? 0 ) + 1;
143 }
144 }
145 }
146 }
147
148 foreach ( $ret as $optionName => $usageStats ) {
149 $this->output( "Usage for <$optionName> (default: '{$defaultOptions[$optionName]}'):\n" );
150 foreach ( $usageStats as $value => $count ) {
151 $this->output( " $count user(s): '$value'\n" );
152 }
153 print "\n";
154 }
155 }
156
160 private function updateOptions() {
161 $dryRun = $this->hasOption( 'dry' );
162 $settingWord = $dryRun ? 'Would set' : 'Setting';
163 $option = $this->getArg( 0 );
164 $fromIsDefault = $this->hasOption( 'old-is-default' );
165 $from = $this->getOption( 'old' );
166 $to = $this->getOption( 'new' );
167
168 // The fromuserid parameter is inclusive, but iterating is easier with an exclusive
169 // range so convert it.
170 $fromUserId = (int)$this->getOption( 'fromuserid', 1 ) - 1;
171 $toUserId = (int)$this->getOption( 'touserid', 0 ) ?: null;
172 $fromAsText = implode( '|', $from );
173
174 if ( !$dryRun ) {
175 $forUsers = ( $fromUserId || $toUserId ) ? "some users (ID $fromUserId-$toUserId)" : 'ALL USERS';
176 $this->warn(
177 <<<WARN
178The script is about to change the options for $forUsers in the database.
179Users with option <$option> = '$fromAsText' will be made to use '$to'.
180
181Abort with control-c in the next five seconds....
182WARN
183 );
184 }
185
186 $userOptionsManager = $this->getServiceContainer()->getUserOptionsManager();
187 $tempUserConfig = $this->getServiceContainer()->getTempUserConfig();
188 $dbr = $this->getReplicaDB();
189 $queryBuilderTemplate = $dbr->newSelectQueryBuilder()
190 ->table( 'user' )
191 ->leftJoin( 'user_properties', null, [
192 'user_id = up_user',
193 'up_property' => $option,
194 ] )
195 ->fields( [ 'user_id', 'user_name' ] )
196 // up_value is unindexed so this can be slow, but should be acceptable in a script
197 ->where( [ 'up_value' => $fromIsDefault ? null : $from ] )
198 // need to order by ID so we can use ID ranges for query continuation
199 // also needed for the fromuserid / touserid parameters to work
200 ->orderBy( 'user_id', SelectQueryBuilder::SORT_ASC )
201 ->limit( $this->getBatchSize() )
202 ->caller( __METHOD__ );
203 if ( $toUserId ) {
204 $queryBuilderTemplate->andWhere( $dbr->expr( 'user_id', '<=', $toUserId ) );
205 }
206
207 if ( $tempUserConfig->isKnown() ) {
208 $queryBuilderTemplate->andWhere(
209 $tempUserConfig->getMatchCondition( $dbr, 'user_name', IExpression::NOT_LIKE )
210 );
211 }
212
213 do {
214 $queryBuilder = clone $queryBuilderTemplate;
215 $queryBuilder->andWhere( $dbr->expr( 'user_id', '>', $fromUserId ) );
216 $result = $queryBuilder->fetchResultSet();
217 foreach ( $result as $row ) {
218 $fromUserId = (int)$row->user_id;
219 $oldOptionIsDefault = true;
220
221 $user = UserIdentityValue::newRegistered( $row->user_id, $row->user_name );
222 if ( $fromIsDefault ) {
223 // $user has the default value for $option; skip if it doesn't match
224 // NOTE: This is intentionally a loose comparison. $from is always a string
225 // (coming from the command line), but the default value might be of a
226 // different type.
227 $oldOptionMatchingDefault = null;
228 foreach ( $from as $oldOption ) {
229 $oldOptionIsDefault = $oldOption != $userOptionsManager->getDefaultOption( $option, $user );
230 if ( $oldOptionIsDefault ) {
231 $oldOptionMatchingDefault = $oldOption;
232 break;
233 }
234 }
235 $fromAsText = $oldOptionMatchingDefault ?? $fromAsText;
236 }
237
238 $this->output( "$settingWord {$option} for {$row->user_name} from '{$fromAsText}' to '{$to}'\n" );
239 if ( !$dryRun && $oldOptionIsDefault ) {
240 $userOptionsManager->setOption( $user, $option, $to );
241 $userOptionsManager->saveOptions( $user );
242 }
243 }
244 $this->waitForReplication();
245 } while ( $result->numRows() );
246 }
247
251 private function deleteOptions() {
252 $dryRun = $this->hasOption( 'dry' );
253 $option = $this->getArg( 0 );
254 $fromUserId = (int)$this->getOption( 'fromuserid', 0 );
255 $toUserId = (int)$this->getOption( 'touserid', 0 ) ?: null;
256 $old = $this->getOption( 'old' );
257
258 if ( !$dryRun ) {
259 $forUsers = ( $fromUserId || $toUserId ) ? "some users (ID $fromUserId-$toUserId)" : 'ALL USERS';
260 $this->warn( <<<WARN
261The script is about to delete '$option' option for $forUsers from user_properties table.
262This action is IRREVERSIBLE.
263
264Abort with control-c in the next five seconds....
265WARN
266 );
267 }
268
269 $dbr = $this->getReplicaDB();
270 $dbw = $this->getPrimaryDB();
271
272 $rowsNum = 0;
273 $rowsInThisBatch = -1;
274 $minUserId = $fromUserId;
275 while ( $rowsInThisBatch != 0 ) {
276 $queryBuilder = $dbr->newSelectQueryBuilder()
277 ->select( 'up_user' )
278 ->from( 'user_properties' )
279 ->where( [ 'up_property' => $option, $dbr->expr( 'up_user', '>', $minUserId ) ] );
280 if ( $this->hasOption( 'touserid' ) ) {
281 $queryBuilder->andWhere( $dbr->expr( 'up_user', '<', $toUserId ) );
282 }
283 if ( $this->hasOption( 'old' ) ) {
284 $queryBuilder->andWhere( [ 'up_value' => $old ] );
285 }
286 // need to order by ID so we can use ID ranges for query continuation
287 $queryBuilder
288 ->orderBy( 'up_user', SelectQueryBuilder::SORT_ASC )
289 ->limit( $this->getBatchSize() );
290
291 $userIds = $queryBuilder->caller( __METHOD__ )->fetchFieldValues();
292 if ( $userIds === [] ) {
293 // no rows left
294 break;
295 }
296
297 if ( !$dryRun ) {
298 $delete = $dbw->newDeleteQueryBuilder()
299 ->deleteFrom( 'user_properties' )
300 ->where( [ 'up_property' => $option, 'up_user' => $userIds ] );
301 if ( $this->hasOption( 'old' ) ) {
302 $delete->andWhere( [ 'up_value' => $old ] );
303 }
304 $delete->caller( __METHOD__ )->execute();
305 $rowsInThisBatch = $dbw->affectedRows();
306 } else {
307 $rowsInThisBatch = count( $userIds );
308 }
309
310 $this->waitForReplication();
311 $rowsNum += $rowsInThisBatch;
312 $minUserId = max( $userIds );
313 }
314
315 if ( !$dryRun ) {
316 $this->output( "Done! Deleted $rowsNum rows.\n" );
317 } else {
318 $this->output( "Would delete $rowsNum rows.\n" );
319 }
320 }
321
322 private function deleteDefaults() {
323 $dryRun = $this->hasOption( 'dry' );
324 $option = $this->getArg( 0 );
325 $fromUserId = (int)$this->getOption( 'fromuserid', 0 );
326 $toUserId = (int)$this->getOption( 'touserid', 0 ) ?: null;
327
328 if ( $option === null ) {
329 $this->fatalError( "Option name is required" );
330 }
331
332 if ( !$dryRun ) {
333 $this->warn( <<<WARN
334This script is about to delete all rows in user_properties that match the current
335defaults for the user (including conditional defaults).
336This action is IRREVERSIBLE.
337
338Abort with control-c in the next five seconds....
339WARN
340 );
341 }
342
343 $dbr = $this->getDB( DB_REPLICA );
344 $dbw = $this->getDB( DB_PRIMARY );
345
346 $queryBuilderTemplate = $dbr->newSelectQueryBuilder()
347 ->select( [ 'user_id', 'user_name', 'up_value' ] )
348 ->from( 'user_properties' )
349 ->join( 'user', null, [ 'up_user = user_id' ] )
350 ->where( [ 'up_property' => $option ] )
351 ->limit( $this->getBatchSize() )
352 ->caller( __METHOD__ );
353
354 if ( $toUserId !== null ) {
355 $queryBuilderTemplate->andWhere( $dbr->expr( 'up_user', '<=', $toUserId ) );
356 }
357
358 $userOptionsManager = $this->getServiceContainer()->getUserOptionsManager();
359 do {
360 $queryBuilder = clone $queryBuilderTemplate;
361 $queryBuilder->andWhere( $dbr->expr( 'up_user', '>', $fromUserId ) );
362 $result = $queryBuilder->fetchResultSet();
363 foreach ( $result as $row ) {
364 $fromUserId = (int)$row->user_id;
365
366 // NOTE: If up_value equals to the default, this will drop the row. Otherwise, it
367 // is going to be a no-op.
368 $user = UserIdentityValue::newRegistered( $row->user_id, $row->user_name );
369 $userOptionsManager->setOption( $user, $option, $row->up_value );
370 $userOptionsManager->saveOptions( $user );
371 }
372 $this->waitForReplication();
373 } while ( $result->numRows() );
374
375 $this->output( "Done!\n" );
376 }
377
381 private function warn( string $message ) {
382 if ( $this->hasOption( 'nowarn' ) ) {
383 return;
384 }
385
386 $this->output( $message );
387 $this->countDown( 5 );
388 }
389}
390
391// @codeCoverageIgnoreStart
392$maintClass = UserOptionsMaintenance::class;
393require_once RUN_MAINTENANCE_IF_MAIN;
394// @codeCoverageIgnoreEnd
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
addArg( $arg, $description, $required=true, $multi=false)
Add some args that are needed.
getArg( $argId=0, $default=null)
Get an argument.
getBatchSize()
Returns batch size.
output( $out, $channel=null)
Throw some output to the user.
fatalError( $msg, $exitCode=1)
Output a message and terminate the current script.
addOption( $name, $description, $required=false, $withArg=false, $shortName=false, $multiOccurrence=false)
Add a parameter to the script.
getDB( $db, $groups=[], $dbDomain=false)
Returns a database to be used by current maintenance script.
waitForReplication()
Wait for replica DB servers to catch up.
hasOption( $name)
Checks to see if a particular option was set.
getOption( $name, $default=null)
Get an option, or return the default.
hasArg( $argId=0)
Does a given argument exist?
getServiceContainer()
Returns the main service container.
maybeHelp( $force=false)
Maybe show the help.
countDown( $seconds)
Count down from $seconds to zero on the terminal, with a one-second pause between showing each number...
addDescription( $text)
Set the description text.
getDefaultOptions(?UserIdentity $userIdentity=null)
Combine the language default options with any site-specific and user-specific defaults and add the de...
getOption(UserIdentity $user, string $oname, $defaultOverride=null, bool $ignoreHidden=false, int $queryFlags=IDBAccessObject::READ_NORMAL)
Get the user's current setting for a given option.
Value object representing a user's identity.
User class for the MediaWiki software.
Definition User.php:119
execute()
Do the actual work.
__construct()
Default constructor.
Build SELECT queries with a fluent interface.
const DB_REPLICA
Definition defines.php:26
const DB_PRIMARY
Definition defines.php:28
$maintClass