$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

Name Type(s) Description

Name	Type(s)	Description
`oldName`	string	Old pathname, must be full disk path.
`newName`	string	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.

oldName

string

Old pathname, must be full disk path.

newName

string

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

Rename a file or directory and update permissions

Usage

Arguments

Return value

Exceptions

Newest forum posts

Latest news

Subscribe to weekly ProcessWire news