$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.

Usage

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

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

Arguments

NameType(s)Description
oldNamestring

Old pathname, must be full disk path.

newNamestring

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)
  • copy (bool): Use copy-then-delete method rather than a file system rename. (default=false) 3.0.178+
  • retry (bool): Retry with 'copy' method if regular rename files, applies only if copy option is false. (default=true) 3.0.178+
  • If given a bool or string for $options the limitPath option is assumed.

Return value

bool

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

Exceptions

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.248

Latest news

  • ProcessWire Weekly #582
    The 582nd issue of ProcessWire Weekly brings in all the latest news from the ProcessWire community. Modules, sites, and more. Read on!
    Weekly.pw / 5 July 2025
  • New ProcessWire admin redesign
    When you upgrade to ProcessWire 3.0.248 or newer (currently the dev branch), you’ll immediately notice something new and beautiful…
    Blog / 9 May 2025
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits