Download the PHP package popphp/pop-dir without Composer

pop-dir

• Overview
• Install
• Quickstart
• Options
• Reading Contents
• The Directory Tree
• Copying a Directory
• Deleting Files
• Empty
• Exceptions

Overview

pop-dir is a component for easily traversing files and subdirectories within a directory.

It is a component of the Pop PHP Framework.

Top

Install

Install pop-dir using Composer.

composer require popphp/pop-dir

Or, require it in your composer.json file

"require": {
    "popphp/pop-dir" : "^5.0.0"
}

Top

Quickstart

Traversing a directory

If you want to traverse the directory recursively and get the full path of each file.

Top

Options

The available boolean options for the $options array parameter are:

The absolute and relative options cannot be used together. If both are passed as true, relative wins, since it's applied after absolute internally.

If absolute is set to true, it will return the absolute path of the files and directories:

If relative is set to true, it will return the relative path of the files and directories:

If neither are passed, it will return only the base file names and directory names:

Each option also has a matching fluent setter/getter pair — setAbsolute()/isAbsolute(), setRelative()/isRelative(), setRecursive()/isRecursive(), setFilesOnly()/isFilesOnly() — so options can be changed after construction instead of (or in addition to) passing them to the constructor:

Calling a setter re-scans the directory immediately, so getFiles()/getTree() reflect the new option right away — there's no separate "apply" or "refresh" step needed.

Top

Reading Contents

Beyond getFiles(), a Dir object implements Countable, IteratorAggregate and ArrayAccess, so its contents can be read the way you'd read a plain array:

Individual entries can be looked up either by their numeric index or by name, and both isset() and [] agree with each other:

Property-style access works the same way via magic methods (__get/__isset), which is handy for numeric offsets or names that aren't valid bare property names (e.g. anything with a . in it):

A Dir object is otherwise read-only through array/property syntax — $dir['x'] = 'y' and $dir->x = 'y' both throw Pop\Dir\Exception, since there's no way to add a tracked entry without it corresponding to a real file on disk. See Deleting Files for the one write operation that is supported (deletion).

Top

The Directory Tree

In addition to the flat getFiles() list, getTree() returns a nested associative array representing the whole directory structure, keyed by the resolved root path:

Subdirectories appear as keys prefixed with the directory separator (e.g. /subdir); files are plain, numerically-indexed basenames. When recursive is false (the default), subdirectory keys are still present in the tree, but their value is always an empty array rather than being expanded — set recursive to true to walk all the way down. A subdirectory that's actually a symlink is likewise never expanded, which also protects against symlink cycles.

Top

Copying a Directory

An entire directory can be copied to another location with copyTo():

By default ($full = true), the source directory itself is created under the destination — the example above produces /path/to/destination/my-dir. Pass false to copy the contents of the source directory directly into the destination instead, without the extra nesting level:

The destination path must already exist — copyTo() does not create intermediate directories for the destination itself, only the source directory's own name underneath it. If $destination doesn't exist, it throws Pop\Dir\Exception rather than failing silently.

Top

Deleting Files

Individual files can be deleted with deleteFile(), or equivalently by unset()-ing an offset:

This removes the file from disk (unlink()) as well as from the Dir object's internal list. It only works on files — attempting to delete a directory entry, a non-existent entry, or a non-writable file throws Pop\Dir\Exception. See Exceptions.

Top

Empty

The directory can be emptied with the emptyDir() method:

The true flag will remove the actual directory as well (use with caution):

emptyDir() recurses into subdirectories automatically and deletes everything it finds. If any individual file can't be deleted (e.g. permissions), it throws Pop\Dir\Exception naming the file, and the operation stops at that point rather than silently skipping it.

By default, emptyDir() does not follow symlinked subdirectories — a symlink entry is removed as a link, leaving whatever it points to untouched. Pass true as the third argument to recurse into a symlinked directory and delete its contents too:

Top

Exceptions

Every error condition in this component throws Pop\Dir\Exception (a plain \Exception subclass), so a single catch covers all of them:

The cases that throw include:

• Constructing a Dir with a path that doesn't exist, or that becomes unreadable partway through a recursive scan.
• Writing through array/property syntax ($dir['x'] = 'y', $dir->x = 'y') — the object is read-only except for deletion.
• Deleting (deleteFile() / unset()) an entry that's a directory, that no longer exists on disk, that isn't writable, or that doesn't match any known entry.
• emptyDir() failing to open the target directory, or failing to delete a file it finds along the way.

Top