WireFileTools / $files

$files->mkdir($path)

Create a directory using ProcessWire's configured directory permissions.

• Arguments: mkdir(string $path, bool $recursive = false, string $chmod = null)
• Returns: bool
• Applies $config->chmodDir automatically.
• $recursive = true creates all intermediate directories (like mkdir -p).
• Swap $recursive and $chmod arguments if preferred 3.0.34.

// Create a single directory
$files->mkdir($config->paths->cache . 'my-module/');

// Create nested directories in one call
$files->mkdir($config->paths->cache . 'my-module/images/', true);

$files->rmdir($path)

Remove a directory, optionally including all contents.

• Arguments: rmdir(string $path, bool $recursive = false, array $options = [])
• Returns: bool
• Be careful with $recursive = true — it will delete everything inside.

// Remove an empty directory
$files->rmdir($config->paths->cache . 'my-module/');

// Remove a directory and everything inside it
$files->rmdir($config->paths->cache . 'my-module/', true);

// Restrict to within site/assets/ for safety
$files->rmdir($path, true, ['limitPath' => $config->paths->assets]);

Key options:

$files->copy($src, $dst)

Copy a file or recursively copy a directory to a new location.

• Arguments: copy(string $src, string $dst, bool|array $options = [])
• Returns: bool
• Applies $config->chmodFile and $config->chmodDir to copied items.
• If $src is a file and $dst is a directory, the filename is preserved under $dst.
• Destination directory is created automatically if it does not exist.

// Copy a directory recursively
$files->copy(
    $config->paths->cache . 'my-module/',
    $config->paths->cache . 'my-module-backup/'
);

// Copy a single file into a directory (keeps filename)
$files->copy('/path/to/source.txt', $config->paths->cache . 'dest-dir/');

// Copy a single file with a new name
$files->copy('/path/to/source.txt', '/path/to/dest.txt');

Key options:

$files->rename($oldName, $newName)

Rename or move a file or directory, updating permissions afterwards.

• Arguments: rename(string $oldName, string $newName, array|bool|string $options = [])
• Returns: bool
• If $newName is only a basename (no directory part), the source directory is assumed.
• Falls back to a copy-then-delete method automatically if a filesystem rename fails.
• Available 3.0.118.

// Rename a file (just the name, same directory)
$files->rename('/path/to/old-name.txt', 'new-name.txt');

// Move a file to a different directory
$files->rename('/path/to/file.txt', '/new/path/file.txt');

Key options:

$files->renameCopy($oldName, $newName)

Same as rename() but always uses the copy-then-delete strategy. Success is determined by whether the copy succeeded, even if the source deletion fails (a warning is logged). This can be useful on servers and/or file systems that don't support (or don't allow) a rename. Available 3.0.178.

$files->renameCopy('/path/to/old.txt', '/path/to/new.txt');

$files->unlink($filename)

Delete a file, with safety checks not present in PHP's unlink().

• Arguments: unlink(string $filename, string|bool $limitPath = false, bool $throw = false)
• Returns: bool
• Rejects relative path traversal (../).
• Pass true for $limitPath to restrict deletion to within /site/assets/.
• Available 3.0.118.

// Delete a file
$files->unlink($config->paths->cache . 'my-module/temp.txt');

// Delete with safety restriction to site/assets/
$files->unlink($filename, true);

// Delete within a specific path
$files->unlink($filename, $config->paths->cache);

$files->find($path)

Recursively find all files in a directory and return a flat array of full path filenames.

• Arguments: find(string $path, array $options = [])
• Returns: array of filenames (sorted)
• Available 3.0.96.

// All files under a directory
$allFiles = $files->find($config->paths->templates);

// Only PHP files
$phpFiles = $files->find($config->paths->templates, [
    'extensions' => ['php'],
]);

// Only PHP and module files, exclude hidden files and a specific directory
$files->find($config->paths->siteModules, [
    'extensions' => 'php module', // string or array
    'excludeHidden' => true,
    'excludeDirNames' => ['_notes'],
]);

// Relative filenames (from the given start path)
$relFiles = $files->find($config->paths->templates, [
    'returnRelative' => true,
]);

Key options:

$files->getCSV($filename)

Read the next row from a CSV file. Call repeatedly in a loop until it returns false. Handles file open/close automatically. Skips blank rows by default.

• Arguments: getCSV(string $filename, array $options = [])
• Returns: array|false — associative array for each row, or false at end of file
• Available 3.0.197. For small files, getAllCSV() may be simpler.

// foods.csv has a header row: Food,Type,Color
while($row = $files->getCSV('/path/to/foods.csv')) {
    echo "$row[Food] is a $row[Type] and is $row[Color]\n";
}

// No header row — returns indexed arrays
while($row = $files->getCSV('/path/to/data.csv', ['header' => false])) {
    echo $row[0];
}

// Custom header (for files with no header row)
$header = ['Name', 'Age', 'City'];
while($row = $files->getCSV('/path/to/data.csv', ['header' => $header])) {
    echo $row['Name'];
}

Key options:

$files->getAllCSV($filename)

Read all rows from a CSV file at once and return an array of arrays. Accepts the same options as getCSV(). Use getCSV() instead for large files to avoid memory limits.

• Arguments: getAllCSV(string $filename, array $options = [])
• Returns: array of row arrays

$rows = $files->getAllCSV('/path/to/foods.csv');
foreach($rows as $row) {
    echo "$row[Food]: $row[Color]\n";
}

$files->zip($zipfile, $files)

Create a ZIP archive.

• Arguments: zip(string $zipfile, array|string $files, array $options = [])
• Returns: array with files (added) and errors keys
• $files may be an array of filenames or a single directory path string.
• Throws WireException on fatal errors (bad path, can't create ZIP, etc.).

// Zip all files from a directory
$result = $files->zip(
    $config->paths->cache . 'backup.zip',
    $config->paths->cache . 'my-module/'
);
echo count($result['files']) . " files added";

// Zip specific files
$result = $files->zip(
    $config->paths->cache . 'export.zip',
    ['/path/to/file1.txt', '/path/to/file2.txt']
);

Key options:

$files->unzip($zipFile, $destinationPath)

Extract a ZIP file to a directory. Applies ProcessWire's configured permissions. Requires the FileValidatorZip core module to be installed.

• Arguments: unzip(string $zipFile, string $destinationPath, array $options = [])
• Returns: array of extracted filenames (excluding destination path)
• Throws WireException on all error conditions.

$dst = $config->paths->cache . 'extracted/';
$extracted = $files->unzip($config->paths->cache . 'archive.zip', $dst);

foreach($extracted as $filename) {
    echo $filename . "\n"; // relative to $dst
}

Key options 3.0.254+:

$files->send($filename)

Send a file to the browser as a download or inline display, and halt execution. Uses $config->fileContentTypes to determine the content type and download behavior.

• Arguments: send(string|bool $filename, array $options = [], array $headers = [])
• Returns: int bytes sent (only if exit option is false)
• Throws WireException on error unless throw option is false.

// Send a file for download
$files->send($config->paths->files . '1234/report.pdf');

// Force download with a specific download filename
$files->send($path, ['downloadFilename' => 'My Report.pdf']);

// Send without halting execution
$bytes = $files->send($path, ['exit' => false]);

// Send string data directly (no file on disk needed)
$files->send(false, [
    'data' => 'Hello world',
    'downloadFilename' => 'hello.txt',
]);

Key options:

$files->render($filename)

Render a PHP file as a ProcessWire template file and return the output as a string. Assumes path relative to /site/templates/ unless an absolute path is given. All API variables ($pages, $config, $user, etc.) are available inside the file.

• Arguments: render(string $filename, array $vars = [], array $options = [])
• Returns: string|bool — rendered output, or false on fatal error

// Render from /site/templates/partials/card.php
$html = $files->render('partials/card.php', ['title' => 'Hello']);

// Use in template output
echo $files->render('partials/header.php');

// With caching 3.0.130+
echo $files->render('partials/nav.php', [], ['cache' => 3600]);

Key options:

$files->include($filename)

Include a PHP file, outputting directly. All ProcessWire API variables are available inside the included file. Assumes relative to current directory for relative filenames.

• Arguments: include(string $filename, array $vars = [], array $options = [])
• Returns: bool — always true
• Use render() instead when you want to capture the output as a string.

$files->include('partials/footer.php');
$files->include('partials/nav.php', ['items' => $page->children]);

$files->includeOnce($filename)

Same as include() but skips execution if the file has already been included.

$files->includeOnce('partials/component.php', $vars);