maintenance/README

   1 MediaWiki's maintenance scripts are PHP scripts that perform maintenance tasks,
   2 and are designed to be run from the command line.
   3
   4 See also: https://www.mediawiki.org/wiki/Manual:Maintenance_scripts
   5
   6 == Running Maintenance Scripts ==
   7
   8 Maintenance scripts are generally executed using the maintenance runner, calling
   9 ''php maintenance/run.php'' followed by the script's name. On most systems, the
  10 shorthand ''maintenance/run'' can also be used. For instance, to run the script
  11 that displays the MediaWiki version, use ''maintenance/run version''.
  12
  13 Maintenance scripts can be called by their simple name, class name, or path.
  14
  15 The simple name corresponds to a file in the maintenance directory:
  16 * ''maintenance/run version'' runs the file ''maintenance/version.php''.
  17
  18 For the class name:
  19 * ''maintenance/run Version'' runs the Version class (using auto-loading from
  20 ''./maintenance/version.php'').
  21
  22 For the path:
  23 * ''maintenance/run ./maintenance/version.php'' runs the file
  24 ''./maintenance/version.php''.
  25
  26 Note that relative file paths must start with "./". Using this form allows for
  27 the use of tab-completion.
  28
  29 Maintenance scripts defined by extensions may also be called by giving their
  30 full class name or full relative path, such as:
  31 * ''maintenance/run ./extension/AbuseFilter/maintenance/SearchFilters.php''
  32 * ''maintenance/run MediaWiki.Extension.AbuseFilter.Maintenance.SearchFilters''
  33
  34 Note how the dot (".") can be used as a namespace separator instead of the
  35 backslash ("\").
  36
  37 If the extension follows the MediaWiki coding conventions for the location and
  38 namespacing of maintenance scripts, they can be invoked using the name of the
  39 extension, followed by a colon (":") and the name of the script file or class:
  40 * ''maintenance/run AbuseFilter:SearchFilters''
  41
  42 For more details on using the script runner, call ''maintenance/run --help''.
  43
  44 For about an individual script, call ''maintenance/run <script> --help ''.
  45
  46 === Running Maintenance Scripts before MW 1.40 ===
  47
  48 The maintenance runner described above was introduced in MediaWiki 1.40. In
  49 MediaWiki version 1.39 and earlier, maintenance scripts had to be run as
  50 standalone PHP scripts, by passing the path the the script to the php interpreter.
  51 For instance:
  52
  53 * ''php maintenance/version.php''
  54
  55 This is still possible for most scripts in 1.40, but it will show a deprecation
  56 warning.
  57
  58 == Creating Maintenance Scripts ==
  59
  60 To create a maintenance script, add a PHP file to the maintenance directory that
  61 contains a class that extends the ''Maintenance'' base class and implement
  62 the ''execute()'' method. At the end of the file, add a return statement that
  63 returns the name of the class.
  64
  65 For example, if your class is called ''Frobnify'', place it in a file called
  66 ''maintenance/Frobnify.php'' and at the end of the file, put the following
  67 statement:
  68 <pre>
  69 return Frobnify::class;
  70 </pre>
  71
  72 You can now run your script by calling ''maintenance/run Frobnify''.
  73
  74 With this, it will however not be possible to run Frobnify.php as a PHP command
  75 line script. ''php maintenance/Frobnify.php'' will fail with an error.
  76
  77 === Supporting direct execution of maintenance scripts ===
  78 Since MediaWiki version 1.40, invoking maintenance scripts directly is now
  79 deprecated, and will show a warning even for scripts that support it.
  80
  81 If you need to support direct invocation for your script, this can be
  82 achieved as follows:
  83
  84 At the top of the script file, place the statement:
  85 <pre>
  86 // @codeCoverageIgnoreStart
  87 require_once __DIR__ . '/Maintenance.php';
  88 // @codeCoverageIgnoreEnd
  89 </pre>.
  90
  91 For maintenance scripts defined in extensions, this is slightly more complex:
  92 <pre>
  93 require_once getenv( 'MW_INSTALL_PATH' ) !== false
  94         ? getenv( 'MW_INSTALL_PATH' ) . '/maintenance/Maintenance.php'
  95         : __DIR__ . '/../../../maintenance/Maintenance.php';
  96 </pre>
  97
  98 Then, at the bottom of the file, replace the return statement with the
  99 following lines:
 100 <pre>
 101 // @codeCoverageIgnoreStart
 102 $maintClass = Frobnify::class;
 103 require_once RUN_MAINTENANCE_IF_MAIN;
 104 // @codeCoverageIgnoreEnd
 105 </pre>
 106
 107 This will allow your script to be executed directly on the PHP command line.
 108 Note however that it will show a warning.