Pagefiles

Pagefiles extends WireArray, so all traversal, filtering, slicing, sorting, and counting methods from WireArray are available. The methods below are specific to file collections.

getFile($name)

Get a Pagefile by its basename. Returns null if not found. Array access with the basename is equivalent.

$file = $page->files->getFile('document.pdf');
$file = $page->files['document.pdf']; // equivalent

findTag($tag)

Return a new Pagefiles collection containing only files that match the given tag expression.

// Single tag
$downloads = $page->files->findTag('download');

// OR: files with any of these tags
$featured = $page->files->findTag('featured|hero|gallery');

// AND: files with all of these tags
$hero = $page->files->findTag('featured,hero');

getTag($tag)

Return the first Pagefile matching the given tag expression, or null if none match. Accepts the same tag syntax as findTag().

$hero = $page->files->getTag('hero');

tags($value)

When called without arguments, returns all tags used by files in this collection as a space-separated string. Pass true to receive an associative array. Pass a tag string to retrieve files matching those tags (alias of findTag()).

$allTags = $page->files->tags();       // "download featured pdf"
$tagsArray = $page->files->tags(true); // ['download' => 'download', ...]

$downloads = $page->files->tags('download');

Destructive changes are queued until the owning page is saved. Call $page->save('field_name') to persist additions, deletions, renames, and duplications.

add($item)

Add a new file to the collection. Accepts a local path, an HTTP(S) URL, or an existing Pagefile object. The file is copied into the page's files directory and given a sanitized, unique basename.

$page->files->add('/path/to/document.pdf');
$page->files->add('https://example.com/image.png');
$page->save('files');

When adding a Pagefile that belongs to a different page, the file is copied into the current page's files directory and marked as temporary until saved.

delete($item)

Queue a Pagefile (or its basename) for deletion. The file is removed from the collection immediately and deleted from disk when the page is saved.

$page->files->delete('old-document.pdf');
$page->save('files');

deleteAll()

Queue every file in the collection for deletion.

$page->files->deleteAll();
$page->save('files');

rename($item, $name)

Queue a rename of a Pagefile. The actual rename occurs when the page is saved.

$file = $page->files->getFile('document.pdf');
$page->files->rename($file, 'report.pdf');
$page->save('files');

clone($item, $options)

Duplicate a Pagefile and insert it into the collection. Returns the new Pagefile or false on failure. The duplicated file is temporary until the page is saved.

$file = $page->files->getFile('document.pdf');
$copy = $page->files->clone($file);
$copy->description = 'Copy of document.pdf';
$page->save('files');

Available options:

path()

Return the full disk path where the files are stored.

$path = $page->files->path();

url()

Return the web-accessible URL where the files are stored.

$url = $page->files->url();

cleanBasename($basename, $originalize = false, $allowDots = true, $translate = false)

Sanitize a filename for use in this collection. Usually called internally when files are added, but available for custom file handling.

$safe = $page->files->cleanBasename('My File.PDF', true);

getFiles()

Return a flat array of disk paths for every file in the collection, including any extra files managed by PagefileExtra.

$paths = $page->files->getFiles();

Pagefiles provides two hookable mutation methods:

$wire->addHookBefore('Pagefiles::delete', function(HookEvent $event) {
    $pagefiles = $event->object; // Pagefiles
    $file = $event->arguments(0); // Pagefile
    // log deletion, check permissions, etc.
});

Individual file URLs and filenames can be hooked on the Pagefile class. See Pagefile for details.

• Pagefiles extends WireArray, so all filtering, sorting, iteration, and array-access features from WireArray are available.
• Items are keyed by basename, so $page->files['report.pdf'] works.
• Files are not actually deleted, renamed, or committed until the owning page is saved.
• Adding a Pagefile that belongs to another page copies the file into the current page's files directory.
• For single-file fields, FieldtypeFile may return a Pagefile object directly when output formatting is on.
• Source file: wire/core/Pagefiles/Pagefiles.php