Extension:Replace Text

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Replace Text

Release status: stable

Implementation Special page
Description Provides a form to let administrators do string replacements on the entire wiki, for both page contents and page titles.
Author(s) Yaron Koren <yaron57@gmail.com> and Niklas Laxström
Latest version 0.9.7 (April 2013)
MediaWiki 1.18 or greater
License GPL
Download  ; and #Download
Added rights

replacetext

Translate the Replace Text extension if possible

Check usage and version matrix; code metrics
Bugs: list open list all report

Replace Text is an extension to MediaWiki that provides a special page to allow administrators to do a global string find-and-replace on both the text and titles of the wiki's content pages.

Download[edit | edit source]

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

One of the extensions tags

Not all extensions have tags. Some extensions have tags for each release, in which case those tags have the same stability as the release. To download a tag

  • Go to the tags list
  • Click the name of the tag you want to download
  • Click "snapshot"
The latest version of one of the extensions branches

Each extension has a master branch containing the latest code (might be unstable). Extensions can have further branches as well.

  • Go to the branches list
  • Click the branch name
  • Click "snapshot"
A snapshot made during the release of a MediaWiki version.

This might be unstable and is not guaranteed to work with the associated MediaWiki version.

After you've got the code, save it into the extensions/ReplaceText directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/ReplaceText.git

Installation[edit | edit source]

After you've obtained a 'ReplaceText' directory (either by extracting a compressed file or downloading via Git), place this directory within the main MediaWiki 'extensions' directory. Then, anywhere in the file 'LocalSettings.php' in the main MediaWiki directory, add the following lines:

require_once( "$IP/extensions/ReplaceText/ReplaceText.php" );

By default, only members of the 'sysop' user group have access to the Replace Text functionality. You can add to or modify the set of allowed users by modifying the $wgGroupPermissions array in LocalSettings.php. To add the permission for 'bureaucrat' users, for instance, you would add the following:

$wgGroupPermissions['bureaucrat']['replacetext'] = true;

Usage[edit | edit source]

Replace Text defines a special page, at 'Special:ReplaceText' (or its equivalent in another language), that handles global searching and replacing. The page initially displays a form for an administrator to fill out the search-and-replace details: the administrator enters a search string and its replacement, the set of namespaces on which to search, as well as choosing whether to replace text within page contents, page titles, or both. Optionally, the administrator can also add two additional filters: the name of a category that all pages must belong to, and a prefix that all page names must start with. When this form is submitted, they are then shown a list of either all the pages that contain that search string, or all the pages whose titles contain the search string, or both. Next to each page name is a checkbox for each, so that they can unselect whichever pages they don't want replaced. The user then can hit "Replace" to do the actual replacement. Once a text replace is done, it is not directly undoable; though you can always run a "reverse" replace, replacing the new string with the original string. For that reason, if the replacement string is blank or is a string that already exists in the wiki, the user is shown a warning message.

If the search string is contained multiple times on a page, every such instance is replaced. Every page's replacements shows up as a (minor) wiki edit, with the administrator who performed the text replacement as the user who made the edit and an edit summary that looks like "Text replace: 'search string' to 'replacement string'".

A page's title cannot be moved to a title that already exists in the wiki. Pages that cannot be moved will be simply listed on the "select" page as being unmovable, without a checkbox near them.

The search is case-sensitive.

Using regular expressions[edit | edit source]

If you click on the "Use regular expressions" checkbox, you can use regular expressions within the search and replacement strings. The set of regular expressions allowed is basically a small subset of the PHP and MySQL regular-expression sets (it has only been tested with MySQL - whether it works on other database systems is unknown). The special characters that one can use in the search string are "( ) . * + ? [ ] |", and within the replacement string one can use values like $1, $2 etc. (To use these as regular characters, you just need to escape them by adding a "\" beforehand - which you would also need to do with the "/" character.) This section will not give a tutorial on using regular expressions (the Wikipedia article is a good place to start for that, as is this page on MySQL regexps), but here is the basic example listed in the inline explanation:

Search string: a(.*)c
Replacement string: ac$1

This would look for pages containing the letter 'a', the letter 'c', and any text in between (signified by the ".*"). It would then put that middle text after the 'a' and 'c' - the "$1" in the replacement string refers to the first element of the search string contained within parentheses (in this case, there's only one).

For every page for which the replace is actually called, the replacement would happen for every occurrence of the search string, not just one - just as happens with regular, non-regular-expression search.

Further example[edit | edit source]

Search string: hello([0-9]*)\.([0-9]*)
Replacement string: $1,$2

This would replace "hello222.555" with "222,555" and "hello2.55" with "2,55"

First the word "hello" is matched. In brackets follows an expression to search for any digits "0-9". The following asterisk finds multiple matches of the preceding element. The brackets and the asterisk get enclosed with parantheses, so we match the complete term and transfer it to $1. The "\." indicates that it's a true dot, and not a special character. The second expression within parentheses is matched and put into $2.

Authors[edit | edit source]

Replace Text was mostly written by Yaron Koren, reachable at yaron57 -at- gmail.com. Important contributions were also made by Niklas Laxström and Ankit Garg (who contributed much of the regular expression code).

Version history[edit | edit source]

Replace Text is currently at version 0.9.7. See the entire version history.

Screenshots[edit | edit source]

Below are images of the workflow of Replace Text. First, the initial page in which "George F. Will" and "George Will" are entered for the target string and replacement string, respectively, and replacing text in page titles is specified as well, on Discourse DB:


Replace-text-prelim-screenshot.png

Note: the check "All" and "None" boxes only show up when using the Vector skin, or skins based off of it.

And here is what the page looks like after the user hits "Continue":


Replace-text-screenshot.png


Hitting "Replace" would replace this value in all of the listed pages, as well as moving the page at the end to its new value.

Code structure[edit | edit source]

The following are the files in the Replace Text extension:

  • README - description of the extension
  • ReplaceText.js - Javascript needed for the forms
  • ReplaceText.php - main file
  • ReplaceTextJob.php - class for the MediaWiki job that does the text replacement
  • ReplaceText.alias.php - special-page aliases
  • ReplaceText.i18n.php - language file
  • SpecialReplaceText.php - the "Special" page that provides the interface for the replacement

Known issues[edit | edit source]

  • The replacement actions themselves are structured as MediaWiki "jobs", to ensure that the system is not overloaded if the user wants to do many at the same time. This means that a large set of replacements will not be done immediately, and may take minutes, hours or even longer to complete. Normally, jobs get activated every time a page is viewed on the wiki; to speed up the process (or slow it down), you change the number of jobs run when a page is viewed; the default is 1. For information on how to change it, see the $wgJobRunRate page. To force the wiki to run all jobs immediately, execute the script runJobs.php (this can be quite server-demanding!).
  • Tied in with the above, there is a bug in MediaWiki 1.22, where jobs that modify pages simply do not get run. If you're running MediaWiki 1.22, it is recommended to add this call in LocalSettings.php, which should restore the correct behavior:
$wgPhpCli = false;
  • In order for redirects not to be created on page moves (i.e. if the "Save the old titles as redirects to the new titles" checkbox is unchecked), you will have to give the relevant user the 'suppressredirect' permission. Assuming you've given the 'replacetext' permission only to sysops, you would need to add the following to LocalSettings.php:
$wgGroupPermissions['sysop']['suppressredirect'] = true;
  • If your revisions are compressed (that is, if $wgCompressRevisions is enabled in LocalSettings.php or the script compressOld.php has been executed with the option -t gzip) then ReplaceText will not work, because it makes use of SQL queries that can't search compressed text.
  • If you have a large number of replacements, some of them may not get done; or you may see an error message that reads "You must select at least one namespace." In both cases, that's due to a limit on the number of form inputs that PHP accepts. This can be fixed in a number of ways:
    • If you have the Suhosin PHP extension installed on your server, that may be source of the problem - you can try temporarily disabling it while you do the replacements.
    • If you have Suhosin installed but want to keep it, you can simply increase the value of the variables suhosin.post.max_vars and suhosin.request.max_vars.
    • The PHP setting max_input_vars (available since PHP 5.3.9) also affects the number of replacements you can do at any time - you can try setting this to a very large number, like 3000.

Contributing to the project[edit | edit source]

Bugs and feature requests[edit | edit source]

Send any bug reports and requests to Yaron Koren, at yaron57 -at- gmail.com.

Contributing patches to the project[edit | edit source]

If you found some bug and fixed it, or created a new feature, please either do a Git commit with your code, or create a patch by going to the "ReplaceText" directory, and typing:

git diff >descriptivename.patch

If you created a patch, please send it, along with a description, to Yaron Koren.

Translating[edit | edit source]

Translation of Replace Text is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.