$files->rename() method

Rename a file or directory and update permissions

Note that this method will fail if pathname given by $newName argument already exists.

Available since version 3.0.118.


// basic usage
$bool = $files->rename(string $oldName, string $newName);

// usage with all arguments
$bool = $files->rename(string $oldName, string $newName, $options = []);



Old pathname, must be full disk path.


New pathname, must be full disk path OR can be basename to assume same path as $oldName.

options (optional)array, bool, string

Options array to modify behavior or substitute limitPath (bool or string) option here.

  • limitPath (bool|string|array): Limit renames to within this path, or boolean TRUE for site/assets, or FALSE to disable (default=false).
  • throw (bool): Throw WireException with verbose details on error? (default=false)
  • chmod (bool): Adjust permissions to be consistent with $config after rename? (default=true)
  • If given a bool or string for $options the limitPath option is assumed.

Return value


True on success, false on fail (or WireException if throw option specified).


Method can throw exceptions on error:

  • WireException - If error occurs and $throw argument was true.

$files methods and properties

API reference based on ProcessWire core version 3.0.161

Twitter updates

  • New ProcessWire query expansion search operators can now add automatic word inflections and lemmatisation, enabling you to build even smarter search engines with ProcessWire. More
    3 July 2020
  • ProcessWire 3.0.161 adds support for selector operator stacking, enabling you automatically broaden searches in a single pages.find() call— More
    26 June 2020
  • ProcessWire 3.0.160 adds powerful new text-searching operators, bringing a new level of power to page-finding API calls, especially when it comes to search engine type queries. Post also includes a demo search engine where you can test it all out live— More
    19 June 2020

Latest news

  • ProcessWire Weekly #321
    In the 321st issue of ProcessWire Weekly we're going to check out the latest core updates, introduce two new third party modules, and check out a brand new site of the week. Read on!
    Weekly.pw / 4 July 2020
  • Powerful new text-searching abilities in 3.0.160
    In ProcessWire 3.0.160 we’ve got some major upgrades and additions to our text-search abilities. This brings a whole new level of power to $pages->find() and similar API calls, especially when it comes to search engine type queries.
    Blog / 19 June 2020
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer