Flourish PHP Unframework

fDirectory

class, v1.0.0b14

Represents a directory on the filesystem, also provides static directory-related methods

Changes:
1.0.0b14Fixed a bug in delete() where a non-existent method was being called on fFilesystem, added a permission check to delete() 8/23/11
1.0.0b13Added the clear() method 1/10/11
1.0.0b12Fixed scanRecursive() to not add duplicate entries for certain nested directory structures 8/10/10
1.0.0b11Fixed scan() to properly add trailing /s for directories 3/16/10
1.0.0b10BackwardsCompatibilityBreak - Fixed scan() and scanRecursive() to strip the current directory's path before matching, added support for glob style matching 3/5/10
1.0.0b9Changed the way directories deleted in a filesystem transaction are handled, including improvements to the exception that is thrown 3/5/10
1.0.0b8Backwards Compatibility Break - renamed getFilesize() to getSize(), added move() 12/16/09
1.0.0b7Fixed __construct() to throw an fValidationException when the directory does not exist 8/21/09
1.0.0b6Fixed a bug where deleting a directory would prevent any future operations in the same script execution on a file or directory with the same path 8/20/09
1.0.0b5Added the ability to skip checks in __construct() for better performance in conjunction with fFilesystem::createObject() 8/6/09
1.0.0b4Refactored scan() to use the new fFilesystem::createObject() method 1/21/09
1.0.0b3Added the $regex_filter parameter to scan() and scanRecursive(), fixed bug in scanRecursive() 1/5/09
1.0.0b2Removed some unnecessary error suppresion operators 12/11/08
1.0.0bThe initial implementation 12/21/07

Variables

->deleted protected

A backtrace from when the file was deleted

Type

array

->directory protected

The full path to the directory

Type

string

Static Methods

::create() public

Creates a directory on the filesystem and returns an object representing it

The directory creation is done recursively, so if any of the parent directories do not exist, they will be created.

This operation will be reverted by a filesystem transaction being rolled back.

Signature

fDirectory create( string $directory, numeric $mode=0777 )

Parameters

string $directory The path to the new directory
numeric $mode The mode (permissions) to use when creating the directory. This should be an octal number (requires a leading zero). This has no effect on the Windows platform.

Throws

fValidationException
When no directory was specified, or the directory already exists

::makeCanonical() public

Makes sure a directory has a / or \ at the end

Signature

string makeCanonical( string $directory )

Parameters

string $directory The directory to check

Returns

The directory name in canonical form

Methods

->__construct() public

Creates an object to represent a directory on the filesystem

If multiple fDirectory objects are created for a single directory, they will reflect changes in each other including rename and delete actions.

Signature

fDirectory __construct( string $directory, boolean $skip_checks=FALSE )

Parameters

string $directory The path to the directory
boolean $skip_checks If file checks should be skipped, which improves performance, but may cause undefined behavior - only skip these if they are duplicated elsewhere

Throws

fValidationException
When no directory was specified, when the directory does not exist or when the path specified is not a directory

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string $method The method to create a callback for

Returns

The callback for the method requested

->__toString() public

Returns the full filesystem path for the directory

Signature

string __toString( )

Returns

The full filesystem path

->clear() public

Removes all files and directories inside of the directory

Signature

void clear( )

->delete() public

Will delete a directory and all files and directories inside of it

This operation will not be performed until the filesystem transaction has been committed, if a transaction is in progress. Any non-Flourish code (PHP or system) will still see this directory and all contents as existing until that point.

Signature

void delete( )

->getName() public

Gets the name of the directory

Signature

string getName( )

Returns

The name of the directory

->getParent() public

Gets the parent directory

Signature

fDirectory getParent( )

Returns

The object representing the parent directory

->getPath() public

Gets the directory's current path

If the web path is requested, uses translations set with fFilesystem::addWebPathTranslation()

Signature

string getPath( boolean $translate_to_web_path=FALSE )

Parameters

boolean $translate_to_web_path If the path should be the web path

Returns

The path for the directory

->getSize() public

Gets the disk usage of the directory and all files and folders contained within

This method may return incorrect results if files over 2GB exist and the server uses a 32 bit operating system

Signature

integer|string getSize( boolean $format=FALSE, integer $decimal_places=1 )

Parameters

boolean $format If the filesize should be formatted for human readability
integer $decimal_places The number of decimal places to format to (if enabled)

Returns

If formatted, a string with filesize in b/kb/mb/gb/tb, otherwise an integer

->isWritable() public

Check to see if the current directory is writable

Signature

boolean isWritable( )

Returns

If the directory is writable

->move() public

Moves the current directory into a different directory

Please note that rename() will rename a directory in its current parent directory or rename it into a different parent directory.

If the current directory's name already exists in the new parent directory and the overwrite flag is set to false, the name will be changed to a unique name.

This operation will be reverted if a filesystem transaction is in progress and is later rolled back.

Signature

fDirectory move( fDirectory|string $new_parent_directory, boolean $overwrite )

Parameters

fDirectory|string $new_parent_directory The directory to move this directory into
boolean $overwrite If the current filename already exists in the new directory, TRUE will cause the file to be overwritten, FALSE will cause the new filename to change

Returns

The directory object, to allow for method chaining

Throws

fValidationException
When the new parent directory passed is not a directory, is not readable or is a sub-directory of this directory

->rename() public

Renames the current directory

This operation will NOT be performed until the filesystem transaction has been committed, if a transaction is in progress. Any non-Flourish code (PHP or system) will still see this directory (and all contained files/dirs) as existing with the old paths until that point.

Signature

void rename( string $new_dirname, boolean $overwrite )

Parameters

string $new_dirname The new full path to the directory or a new name in the current parent directory
boolean $overwrite If the new dirname already exists, TRUE will cause the file to be overwritten, FALSE will cause the new filename to change

->scan() public

Performs a scandir() on a directory, removing the . and .. entries

If the $filter looks like a valid PCRE pattern - matching delimeters (a delimeter can be any non-alphanumeric, non-backslash, non-whitespace character) followed by zero or more of the flags i, m, s, x, e, A, D, S, U, X, J, u - then preg_match() will be used.

Otherwise the $filter will do a case-sensitive match with * matching zero or more characters and ? matching a single character.

On all OSes (even Windows), directories will be separated by /s when comparing with the $filter.

Signature

array scan( string $filter=NULL )

Parameters

string $filter A PCRE or glob pattern to filter files/directories by path - directories can be detected by checking for a trailing / (even on Windows)

Returns

The fFile (or fImage) and fDirectory objects for the files/directories in this directory

->scanRecursive() public

Performs a recursive scandir() on a directory, removing the . and .. entries

Signature

array scanRecursive( string $filter=NULL )

Parameters

string $filter A PCRE or glob pattern to filter files/directories by path - see scan() for details

Returns

The fFile (or fImage) and fDirectory objects for the files/directories (listed recursively) in this directory

->tossIfDeleted() protected

Throws an exception if the directory has been deleted

Signature

void tossIfDeleted( )