Summary: Rename a wiki page from a browser
Version: 2014-02-27 (aka "2.0.21" inside of the code)
Prerequisites: pmwiki-2.2.56 or above, php 5.3 or above
Status: stable
Maintainer: jr
Users: (View / Edit)
Discussion: RenamePage-Talk?
Categories: System tools, PHP55


Provide a way to rename a wiki page from a browser, either within groups or across groups.

As an extra bonus, this also provides a way for cross-group include directives to qualify any unqualified links.

And you get ?action=links or (:linkslist pagename:) to generate an alphabetic list of all links on the current page or on pagename respectively.


Please note. The PublishPDF library includes the RenamePage recipe.

The following version is compatible with php 5.5:

rename1_0.phpΔ is a script that adds ?action=rename, ?action=links and (:linkslist pagename:) to PmWiki.

Important: the latest version requires that you also download and install either:

You must use one. Do not use both. Otherwise, php returns a fatal error for a call to an undefined function.

Installation Instructions

Put the scripts in cookbook/ as per the module guidelines. The script is only loaded if its actions are requested. The lines work for farm and non-farm installations. Update config.php as follows:

## Activate the RenamePage recipe.
if ($action == 'rename' || $action == 'postrename' || $action == 'links' ) {
Note: If you are using Markup Extensions then you don't need renamehelper.php and you should not use the line that includes renamehelper.php: just omit that line or comment it out with ##.

Instructions for use

  1. Navigate to the page you want to rename and add ?action=rename to the URI in your browser's address bar.
  2. Choose an existing group from the pick list of available groups (or leave the page in the current group). If a new group is to be created, leave the default group selected.
  3. Enter a new Pagename or key Groupname/Pagename in the text field.
  4. Decide what you want to do with any unqualified links (ie links without a group name qualifier). Any such links are listed below the form. Options are:
    1. do nothing (the default)
    2. add the old group name
    3. add the new group name
  5. Press Rename.

The original page is still there, but now redirects to the renamed page.

Depending on your appetite for risk, you may wish to test this on some non-critical pages before attempting a wholescale wiki restructuring.

Edit integration

To have this functionality as part of the normal edit action add a (rename) link after the 'Editing Group.Page' heading. Something like:

 $PageEditFmt =
   str_replace('</h1>',' <a href=\'$PageUrl?action=rename\'>'.

Alternatively edit Site.PageActions and add this

* %item rel=nofollow class=rename accesskey=$[ak_rename]% [[{*$FullName}?action=rename | $[Rename] ]]

Cool new features:

Qualified Include

(:includeg Group.PageName:)

This qualifies any unqualified links it finds on PageName. All regular include capabilities should still work.

There is currently a bug in this feature in that it interprets [[<<]] markup as an unqualified link called 'Lt Lt'. swestrup November 19, 2007, at 10:45 PM
This happened to me when I renamed a page into a different group, and created a link [[Gallery/&lt;&lt;]] simon March 21, 2009, at 06:03 PM

List of all links on the specified page

Yet another cool new feature:

(:linkslist pagename:)

This gives an alphabetic list of all links on the specified page. Useful in a SideBar. Or, to see all links on the current page, append ?action=links to the URI in your browser's address bar.


  • 23 September 2005 -- minor bug fixes plus file reported as containing blank lines at the start
  • 19 July 2005 -- removed bug which caused qualified links to be shown in the list
  • 11 July 2005 -- fix bug which caused some intermap references to be treated as links
  • 27 May 2005 -- fix incompatibility with beta 35 and above, add action=links, tidy code
  • 8 April 2005 -- add ability to qualify unqualified links
  • 17 March 2005 -- fix problem causing some configurations to ignore the Rename action; thanks to Jo and Menachem
  • 7 February 2005 -- changed pagename to n and PageName to FullName
  • 12 Nov 2004 converted from PmWiki 1 version




After using the rename function, the new page does not appear in the AllRecentChanges. Why? Is it because the rename function is not considered as a "change"? - kt007 December 02, 2004, at 08:59 AM

Correct. If you click on the old name in AllRecentChanges, PmWiki will redirect you to the new name. The script works by doing a file copy, rather than 'edit old and post new'. Of course, as soon as you edit the new page, AllRecentChanges gets updated. jr

it's not possible to use the attached script. should it be a .zip file? Han (05 feb 05)

My browser insists on saving it with a .html extension. You need to change this to .php to make it usable.

It the script doesn't change the Pagereferences but makes a redirection from the old pagename to the new one. Is this the wanted behaviour, or is something wrong on my installation? So the original linkreference in all other pages still be the same. Is there a option to change the pagereferences to the new pagename instead of redirect? noskule

Is it possible to rename a group?

See Also

MovePage is smaller and moves or copies the page including all of its history, as well as adding a note in the page history & recent changes that the copy/move has been made.

WikiSh includes a {(mv ...)} command which will move/rename one or more pages (moving an entire group is possible). Note that references & links are not handled explicitly, but another command {(sed -i 's/searchfor/replacewith/' ...)} allows a generic search & replace which could be used with a little planning to handle these links. An example can be found at WikiShExamples#RenamePage (for an individual page) or WikiShExamples#RenameGroup (for an entire group) showing how this can be done.


PageStore compatibility

The current semantics of a rename operation is:

  • Check that no page of the target name exists
  • Create that page with contents of old page
  • Edit old page to make it a redirect to the new one

I think that it can be made entirely compatible with PageStore: simply read the old page, then write it with the new name. I think that would mean rewriting CopyPage like this (it's even shorter *gg*):

  $page = RetrieveAuthPage ($old, 'edit');
  WritePage ($new, $page);
Done 27 May 2005

Rename Password

You should also add the possibility to set a password for renaming (This should be already possible within the config.php with $DefaultPasswords['rename']) in the attributes page. Adding an entry to the array PageAttributes would place a query into the attributes page. But handling the password has to be added also. Klonk

I'll have to investigate this -- it's not clear to me how to make it work. jr
All you have to do is to RetrieveAuthPage($pagename, 'rename'). However, I think it's enough to require edit privilege - the only thing that remains to be done is to change the RetrieveAuthPage($pagename, 'read') in line 30 with RetrieveAuthPage($pagename, 'edit'). Joachim Durchholz
Right. Done.

Updating unqualified links

If an author moves a page from one group to another, any unqualified wiki links in the page will now probably refer to non-existing pages. Sometimes this is what one wants; sometimes one will need to edit the page and update some or all of the links to insert a group qualifier. If one were moving a lot of pages this could be a bit of a chore. On the other hand, if one were moving a lot of pages, chances are the unqualified links will point to pages that are also being moved.

It is a fairly minor task for the script to insert the original group name as a qualifier on all unqualified page references. This could perhaps be an option via a check box on the rename form. If there is a demand for this capability, we can look at adding it. Cast a vote from 1 (not required) to 5 (no use without this feature).

Coming soonNow implemented as an option to apply either the original group name or the new group name (or do nothing) to all unqualified links.

Here's an alternate proposal. Don't use a single checkbox, but list all the unqualifiedly-linked-to pages with a checkbox that indicates whether they should be made qualified. (The list of linked-to page should be produced by finding all unqualified links and eliminating any duplicates.)

The page names in the list should be links to the pages. This allows the end user to double-check these names and make sure that they really should be moved. (The Rename page might add a note indicating that these links are best opened using "Open in New Window" or "Open in New Tab", so that the Rename page is kept open.)

Great idea -- I'll need to think about how to implement it. Displaying a list of unqualified links would be a start... jr
A version that lists unqualified links is coming soonnow implemented. It correctly detects and ignores links inside ... and `-escaped wiki words. It also correctly ignores special cases like jr and implied groups, like references to PmWiki. Providing an option to select which ones to qualify with the group name looks hard! jr

Suggestion for the Form

It would be helpful to the users if the form were to provide instructions, especially identifying the option of keying Groupname/Pagename in the text field as a method of creating a new group for the renamed page.

I'll investigate including a Site.RenameQuickReference page that automatically gets displayed (and of course can be edited). And I hadn't realised that one could rename a page into a new group in that way. I'm quite surprised that it works! jr

The present ?action=rename adds (:redirect Groupname.Pagename:) to the old page. I think of this as a temporary measure; I usually want to complete the process by finding existing links to the original page, and updating those links to point them to the new page. It would be helpful if, below the redirection directive on the original page, the recipe added (:pagelist link={$FullName} fmt=simple:). This would allow the user to follow the "redirected from" link back, from the new page to the original page, where the user could easily edit out the redirect and preview in order to identify links to the old page that need to be updated. -- Tegan Dowling

The following changes update the script so someone can use, for example,

$HandleAuth['rename'] = 'admin';

in config.php to change the required authorization level for renaming a page.

> SDV($HandleAuth['rename'],'edit');
> SDV($HandleAuth['postrename'],$HandleAuth['rename']);
< function HandleRename($pagename) {
> function HandleRename($pagename,$auth) {
>   $page = RetrieveAuthPage($pagename, $auth, true, READPAGE_CURRENT);
>   if (!$page) Abort('?unauthorized');
< function HandlePostRename($pagename) {
> function HandlePostRename($pagename,$auth) {
<     $page = RetrieveAuthPage($pagename,"edit");
>     $page = RetrieveAuthPage($pagename,$auth);

--Hagan 2006-01-18

I made an actual rename instead of a redirected rename function. I made this update in the rename.php file. I don't know about the unqualified links and stuff so I didn't include that in my function. Perhaps someone can incorporate that stuff in. I posted this in ( and a related fix in ( Anyhoo, here's my version of it:

function HandlePostRename($pagename) {

  global $WikiDir;

  $newpagename = MakePageName($pagename, stripmagic($_POST['group'].'.'.$_POST['renametext']));

  if (PageExists($newpagename)) {
    Abort("'$newpagename' already exists");

  # Get list backlinks to given page plus page index file
  $backlinks = PageIndexGrep($pagename, false);

  # Make sure backlinks don't include the new name
  $backlinks = array_diff($backlinks, (array)$newpagename);

  # Create search regex for old link
  $linkname_regex = preg_replace('/\./', '\/', $pagename);
  $pagename_regex = preg_replace('/\./', '\.', $pagename);

  # Create replacement text for new link
  $newlinkname = preg_replace('/\./', '/', $newpagename);

  # Search and replace all occurances of the oldlinkname with the newlinkname
  foreach ($backlinks as $backlink) {
    $page = RetrieveAuthPage($backlink, 'edit');
    $page['text'] = preg_replace("/$linkname_regex/", $newlinkname, $page['text']);
    $page['targets'] = preg_replace("/$pagename_regex/", $newpagename, $page['targets']);

  # Do the actual file renaming
  $oldqualifiedfile = $WikiDir->pagefile($pagename);
  $newqualifiedfile = $WikiDir->pagefile($newpagename);
  rename($oldqualifiedfile, $newqualifiedfile);

  # Change the internal name property to the new name by just writing the page
  $page = ReadPage($newpagename);

  # Update the index for all pages that have changed
  # Keep the old page name in the backlinks to remove it from the pageindex file
  $backlinks[] = $newpagename;



--Azbok? 2007-01-14

I needed functionality for moving attachments associated with a page when renaming the page (by "associated with" I mean attachments which are actually linked on the page and are unqualified, i.e. in the same namespace as the page). I have added something basic -- it works for me (on Linux), but it is by no means thoroughly tested, and it's not very polished.

CAVEAT: I couldn't think of a tidy way to determine the upload prefix of a page other than the current page, so I use an additional variable in the main local config file.

Here is my modified copy (based on version 2.0.17): rename-20080401.phpΔ

Instructions for use:

  1. make sure you have uploads enabled; this modification relies on some variables defined in that component (I don't know why you'd use it otherwise. ;) ).
  2. replace the rename recipe file with the modified version.
  3. in your local config file, add $UploadPrefixes['default'] = $UploadPrefixFmt; and add $UploadPrefixes['SomeGroup or SomeGroup.SomePage'] = 'some pattern'; for every group or page which has a different upload prefix.
  4. now the rename page should show an extra set of options, and ask whether you wish to ignore, move or copy local attachments used on the page. Ignore is selected by default. It should also show a list of linked attachments at the bottom.
  • Links to non-existent files are listed, but non-existent files won't be moved.
  • Qualified links won't be listed, even if they point to files in the local namespace.

This modification could probably be extended to offer the option of qualifying unqualified file links.

Adrianna April 01, 2008, at 09:43 AM

There is a bug with unqualified links

It retrieves CamelCased words that are definitely no links at all.

The above line produces an unqualified link to page CamelCased.
If you then choose to Add group to any Unqualified Links postrename aborts with fatal PHP error.

Tontyna February 03, 2009, at 03:03 AM

I miss authentication. Currently everyone can rename pages. This should be selectable and default to 'edit'. Someone please check and fix it. I tried but failed.

Klonk February 10, 2010, at 04:36 PM

It's very strange. For some pages, the function is running perfectly, for other, I've a blank page with this error on the log :
[Wed Feb 24 18:28:31 2010] [error] [client xxx.yyy.yyy.zzz] PHP Fatal error: Call to undefined function QualifyFLink() in /var/www/wiki/cookbook/rename.php on line 113

Any Idea ?

Note: I discover that the issue append only if there is a reference to other pages.

rdursel? February 24, 2010, at 11:32 AM

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.