spunQ_Folder Class Reference

A class describing a folder. More...

Inheritance diagram for spunQ_Folder:

List of all members.

Public Member Functions

getParent ()

Alias for getContainingFolder().

getFilesRecursive (array $suffixes, &$newest)

Gets all files with any of the given suffixes in the folder recursively.

getFilesWithAliasRecursive (array $suffixes, &$newest, $alias)

Almost the same as getFilesRecursive(), but generates aliases as well.

getFilesByRegex ($regex, $includeHidden=true)

getFilesBySuffix ($suffix, $includeHidden=true)

Get all files in this folder with given suffix.

getFiles ($includeHidden=true)

Fetches all files in this folder.

getFolders ($includeHidden=true)

Fetches all sub-folders in this folder.

getFile ($name)

Gets a file in - or relative to - this folder.

getFolder ($name)

Gets a folder in - or relative to - this folder.

getPathTo (spunQ_IFileNode $node)

Will give the path from this folder to another file node.

getBreadcrumbsTo (spunQ_IFileNode $node)

Does the same as getPathTo(), merely the result has a different format.

create ()

Makes sure this folder exists - creating parent folders if necessary.

createTemporaryFile ()

Creates a temporary file in this folder.

assureExists ()

Throws an exception if this folder does not exist.

isEmpty ()

Checks whether this folder contains any files or folders.

delete ()

Deletes this folder from the file system including anything in it.

moveTo ($folder, $overwrite, $newName=NULL)

Moves this folder into another directory (and optionally renames it).

exists ()

Whether this node already exists in the file system.

residesIn (spunQ_IFolder $folder)

Checks whether this file is in given folder or one of its subfolders.

isReadable ()

Whether the node is readable.

getPath ()

Returns the path pointing to the node.

getPrettyPath ()

Returns the most unique and human-readable path.

getContainingFolder ()

Returns the folder this node is residing in.

getName ()

Returns the name of this node, deprived of its path.

getLastAccessTime ()

Returns the time of last access of this node.

getLastModificationTime ()

Returns the time of last modification of this node.

__toString ()

Returns getPrettyPath().

Static Public Member Functions

static current ()

Provides the spunQ_Folder object of the folder calling file is in.

static getByAlias ($alias, $throwException=true)

Allows access to configured folders.

static _init ()

Initializes the class.

static _shutdown ()

Deletes all temporary folders.

static get ($path)

Factory method.

static isHidden ($path)

Whether a path indicates a hidden node (one that starts with a dot).

static getSysTmp ()

Gets the systems temporary folder.

static createTemporaryFolder ()

Creates a temporary folder.

static pathIsAbsolute ($filePath)

Tests if a givebn file path is absolute or relative.

static prettifyPath ($path)

Makes transformations to a path string to make it more readable.

Protected Attributes

$path

The path pointing to the node.

Private Member Functions

getFilesWithAliasRecursiveImplementation ($path, $prefix, $suffixRegex, &$newest)

Helper function for getFilesWithAliasRecursive().

Static Private Member Functions

static getFilesRecursiveImplementation ($path, $suffixRegex, &$newest)

Helper function for getFilesRecursive().

Static Private Attributes

static $temporaryFolders = array()

Array of temporary folders that will be removed on shutdown.

Detailed Description

A class describing a folder.

Todo:: getFilesRecursive() should rather be getFilesBySuffixRecursive()

Definition at line 7 of file Folder.class.php.

Member Function Documentation

spunQ_FileNode::__toString ( ) [inherited]

Returns getPrettyPath().

Returns:: string

Definition at line 162 of file FileNode.class.php.

static spunQ_Folder::_init ( ) [static]

Initializes the class.

Just registers a shutdown hook to delete temporary folders.

Returns:: void

Definition at line 42 of file Folder.class.php.

static spunQ_Folder::_shutdown ( ) [static]

Deletes all temporary folders.

Returns:: void

Definition at line 51 of file Folder.class.php.

spunQ_Folder::assureExists ( )

Throws an exception if this folder does not exist.

Returns:: void

Exceptions:

spunQ_IOException

Implements spunQ_IFolder.

Definition at line 276 of file Folder.class.php.

spunQ_Folder::create ( )

Makes sure this folder exists - creating parent folders if necessary.

Doesn't do anything if the node already exists.

Returns:: spunQ_IFolder $this

Implements spunQ_IFolder.

Definition at line 257 of file Folder.class.php.

spunQ_Folder::createTemporaryFile ( )

Creates a temporary file in this folder.

Returns:: spunQ_IFile

Exceptions:

spunQ_IOException

Implements spunQ_IFolder.

Definition at line 269 of file Folder.class.php.

static spunQ_Folder::createTemporaryFolder ( ) [static]

Creates a temporary folder.

The folder will have a random name.

Returns:: spunQ_Folder

Definition at line 91 of file Folder.class.php.

static spunQ_Folder::current ( ) [static]

Provides the spunQ_Folder object of the folder calling file is in.

You can use this function to get the folder you're currently in, if you want a file relative to that one. Makes use of spunQ_Backtrace.

Returns:: spunQ_File

Definition at line 15 of file Folder.class.php.

spunQ_Folder::delete ( )

Deletes this folder from the file system including anything in it.

Returns:: spunQ_IFolder $this

Implements spunQ_IFolder.

Definition at line 298 of file Folder.class.php.

spunQ_FileNode::exists ( ) [inherited]

Whether this node already exists in the file system.

It is perfectly valid for an object to describe a non-existent node.

Returns:: bool

Implements spunQ_IFileNode.

Definition at line 78 of file FileNode.class.php.

static spunQ_Folder::get ( $ path ) [static]

Factory method.

Creates a folder object that will operate on the given path.

Parameters:

$path

A string describing a path on the file system

Returns:: spunQ_Folder

Definition at line 64 of file Folder.class.php.

spunQ_Folder::getBreadcrumbsTo ( spunQ_IFileNode $ node )

Does the same as getPathTo(), merely the result has a different format.

Parameters:

$node

Another file node.

Returns:: array<string>

Implements spunQ_IFolder.

Definition at line 250 of file Folder.class.php.

static spunQ_Folder::getByAlias	(	$	alias,
		$	throwException = `true`
	)			`[static]`

Allows access to configured folders.

Any configuration value with a key that starts with spunQ.folder.

Parameters:

	$alias	Last part of the configuration key.
	$throwException	Whether an exception should be thrown if no such key was configured.

Returns:: spunQ_Folder

Definition at line 29 of file Folder.class.php.

spunQ_FileNode::getContainingFolder ( ) [inherited]

Returns the folder this node is residing in.

Returns:: spunQ_IFolder

Implements spunQ_IFileNode.

Definition at line 127 of file FileNode.class.php.

spunQ_Folder::getFile ( $ name )

Gets a file in - or relative to - this folder.

Note that this function does not ensure that the file actually exists. This can be achieved by a later call to exists() or create().

Parameters:

$name

A string describing a file relative to this folder.

Returns:: spunQ_IFile

Implements spunQ_IFolder.

Definition at line 211 of file Folder.class.php.

spunQ_Folder::getFiles ( $ includeHidden = true )

Fetches all files in this folder.

Parameters:

$includeHidden

Whether hidden files should be returned, too.

See also:: isHidden()

Returns:: array

Implements spunQ_IFolder.

Definition at line 163 of file Folder.class.php.

spunQ_Folder::getFilesBySuffix	(	$	suffix,
		$	includeHidden = `true`
	)

Get all files in this folder with given suffix.

Parameters:

$suffix

Either a suffix string or an array of suffixes. Not dot is prepended to the suffix, so if this value is 'ml', all files ending on 'html' will match, too. Whether to return hidden files.

Returns:: array<string> Paths of the files.

Implements spunQ_IFolder.

Definition at line 152 of file Folder.class.php.

spunQ_Folder::getFilesRecursive	(	array $	suffixes,
		&$	newest
	)

Gets all files with any of the given suffixes in the folder recursively.

This function is optimized for speed, so it will not return objects.

Parameters:

	$folder	The folder to search in. Sub-folders of this folder will be processed recursively.
	$suffixes	List of file suffixes. Any file having one of the suffixes matches and will be returned.
	$newest	Out-parameter containing the highest mtime (last modification time) value of all returned files and each folder that was processed in recursive calls. This value will be used to verify the validity of caches holding the result of this function.

Returns:: array<string> Absolute file paths matching the criteria given above. This is not returned as spunQ_IFile objects to avoid a performance impact due to object creation.

Implements spunQ_IFolder.

Definition at line 117 of file Folder.class.php.

static spunQ_Folder::getFilesRecursiveImplementation	(	$	path,
		$	suffixRegex,
		&$	newest
	)			`[static, private]`

Helper function for getFilesRecursive().

Takes the parameters in an optimized form and loops.

Parameters:

	$path	The string path of the file to process.
	$suffixRegex	A regex that will match files with the desired suffixes.
	$newest	Most recently modified file's timestamp.

Returns:: array The values are stored as keys, to enhance speed. getFilesRecursive() will return the array_keys(). {2009-11-18} We made several implementations of this function using RecursiveIteratorIterator, glob and regular expressions and found the regular expressions to be the fastest by a great margin.

Definition at line 362 of file Folder.class.php.

spunQ_Folder::getFilesWithAliasRecursive	(	array $	suffixes,
		&$	newest,
		$	alias
	)

Almost the same as getFilesRecursive(), but generates aliases as well.

The alias consists of three parts, which are separated by dots:

a root alias part
a list of folder names
the name of the filed, stripped of the matching suffix.

So this file would have the alias 'spunQ.file.Folder', if $spunQFolder->getFilesRecursive(array('.class.php'), $newest, 'spunQ') was called.

Parameters:

	$suffixes	List of file suffixes. Any file having one of the suffixes matches and will be returned.
	$newest	Out-parameter containing the highest mtime (last modification time) value of all returned files and each folder that was processed in recursive calls. This value will be used to verify the validity of caches holding the result of this function.
	$alias	Alias for all files in this folder. This should be the module name, or a similar top-level string.

Returns:: array Same as getFilesRecursive(), except that the array key of each entry is the files alias.

Implements spunQ_IFolder.

Definition at line 126 of file Folder.class.php.

spunQ_Folder::getFilesWithAliasRecursiveImplementation	(	$	path,
		$	prefix,
		$	suffixRegex,
		&$	newest
	)			`[private]`

Helper function for getFilesWithAliasRecursive().

Takes the parameters in an optimized form and loops.

Parameters:

	$path	The string path of the file to process.
	$prefix	The string to prepend to each file. Will contain a trailing dot if it is not the empty string.
	$suffixRegex	A regex that will match files with the desired suffixes.
	$newest	Most recently modified file's timestamp.

Returns:: array The values are stored as keys, to enhance speed. getFilesRecursive() will return the array_keys().

Definition at line 390 of file Folder.class.php.

spunQ_Folder::getFolder ( $ name )

Gets a folder in - or relative to - this folder.

Note that this function does not ensure that the folder actually exists. This can be achieved by a later call to exists() or create().

Parameters:

$name

A string describing a folder relative to this folder.

Returns:: spunQ_IFolder

Implements spunQ_IFolder.

Definition at line 218 of file Folder.class.php.

spunQ_Folder::getFolders ( $ includeHidden = true )

Fetches all sub-folders in this folder.

Parameters:

$includeHidden

Whether hidden folders should be returned, too.

See also:: isHidden()

Returns:: array

Implements spunQ_IFolder.

Reimplemented in spunQ_SourceFolder.

Definition at line 187 of file Folder.class.php.

spunQ_FileNode::getLastAccessTime ( ) [inherited]

Returns the time of last access of this node.

Returns:: int The result is a unix-timestamp

Exceptions:

spunQ_IOException

If the timestamp could not be read.

Implements spunQ_IFileNode.

Definition at line 141 of file FileNode.class.php.

spunQ_FileNode::getLastModificationTime ( ) [inherited]

Returns the time of last modification of this node.

Returns:: int The result is a unix-timestamp

Exceptions:

spunQ_IOException

If the timestamp could not be read.

Implements spunQ_IFileNode.

Definition at line 151 of file FileNode.class.php.

spunQ_FileNode::getName ( ) [inherited]

Returns the name of this node, deprived of its path.

Returns:: string

Implements spunQ_IFileNode.

Definition at line 134 of file FileNode.class.php.

spunQ_Folder::getParent ( )

Alias for getContainingFolder().

Returns:: spunQ_IFolder

Implements spunQ_IFolder.

Definition at line 110 of file Folder.class.php.

spunQ_FileNode::getPath ( ) [inherited]

Returns the path pointing to the node.

Returns:: string

Implements spunQ_IFileNode.

Definition at line 102 of file FileNode.class.php.

spunQ_Folder::getPathTo ( spunQ_IFileNode $ node )

Will give the path from this folder to another file node.

Parameters:

$node

Another file node.

Returns:: string

Implements spunQ_IFolder.

Definition at line 225 of file Folder.class.php.

spunQ_FileNode::getPrettyPath ( ) [inherited]

Returns the most unique and human-readable path.

If the file exists, the builtin function realpath() is used. Otherwise, a better-looking path is achieved through string manipulation, i.e. '../a/../d/./' becomes '../d/'.

Returns:: string

Implements spunQ_IFileNode.

Definition at line 109 of file FileNode.class.php.

static spunQ_Folder::getSysTmp ( ) [static]

Gets the systems temporary folder.

Returns:: spunQ_Folder

Definition at line 82 of file Folder.class.php.

spunQ_Folder::isEmpty ( )

Checks whether this folder contains any files or folders.

Returns:: bool

Implements spunQ_IFolder.

Definition at line 286 of file Folder.class.php.

static spunQ_Folder::isHidden ( $ path ) [static]

Whether a path indicates a hidden node (one that starts with a dot).

Parameters:

$path

An arbitrary file path.

Returns:: boolean

Definition at line 73 of file Folder.class.php.

spunQ_FileNode::isReadable ( ) [inherited]

Whether the node is readable.

Returns:: bool

Implements spunQ_IFileNode.

Definition at line 95 of file FileNode.class.php.

spunQ_Folder::moveTo	(	$	folder,
		$	overwrite,
		$	newName = `NULL`
	)

Moves this folder into another directory (and optionally renames it).

Parameters:

	$folder	the folder to move to. Either a spunQ_IFolder or a string.
	$overwrite	Whether the destination folder should be overwritten. Warning: The destination folder will be replaced(!), not extended.
	$newName	The folder will be renamed, too if this is set.

Returns:: spunQ_IFolder $this

Implements spunQ_IFolder.

Definition at line 317 of file Folder.class.php.

static spunQ_FileNode::pathIsAbsolute ( $ filePath ) [static, inherited]

Tests if a givebn file path is absolute or relative.

Parameters:

$filePath

The file path - a string.

Returns:: boolean

Definition at line 14 of file FileNode.class.php.

static spunQ_FileNode::prettifyPath ( $ path ) [static, inherited]

Makes transformations to a path string to make it more readable.

Removes references to current and upper directories (/foo/.. or foo/.), for example. Assumes that the path has a slash as delimiter. if you want to use this function on a windows path, make sure to replace backslashes by forward slashes beforehand.

Parameters:

$path

The path string to transform.

Returns:: string

Definition at line 34 of file FileNode.class.php.

spunQ_FileNode::residesIn ( spunQ_IFolder $ folder ) [inherited]

Checks whether this file is in given folder or one of its subfolders.

Parameters:

$folder

The folder to test against.

Returns:: bool

Implements spunQ_IFileNode.

Definition at line 85 of file FileNode.class.php.

Member Data Documentation

spunQ_FileNode::$path [protected, inherited]

The path pointing to the node.

string

Definition at line 64 of file FileNode.class.php.

spunQ_Folder::$temporaryFolders = array() [static, private]

Array of temporary folders that will be removed on shutdown.

Type:: array<spunQ_Folder>

Definition at line 105 of file Folder.class.php.

The documentation for this class was generated from the following file:

Folder.class.php


Public Member Functions
	getParent ()
	Alias for getContainingFolder().
	getFilesRecursive (array $suffixes, &$newest)
	Gets all files with any of the given suffixes in the folder recursively.
	getFilesWithAliasRecursive (array $suffixes, &$newest, $alias)
	Almost the same as getFilesRecursive(), but generates aliases as well.
	getFilesByRegex ($regex, $includeHidden=true)
	getFilesBySuffix ($suffix, $includeHidden=true)
	Get all files in this folder with given suffix.
	getFiles ($includeHidden=true)
	Fetches all files in this folder.
	getFolders ($includeHidden=true)
	Fetches all sub-folders in this folder.
	getFile ($name)
	Gets a file in - or relative to - this folder.
	getFolder ($name)
	Gets a folder in - or relative to - this folder.
	getPathTo (spunQ_IFileNode $node)
	Will give the path from this folder to another file node.
	getBreadcrumbsTo (spunQ_IFileNode $node)
	Does the same as getPathTo(), merely the result has a different format.
	create ()
	Makes sure this folder exists - creating parent folders if necessary.
	createTemporaryFile ()
	Creates a temporary file in this folder.
	assureExists ()
	Throws an exception if this folder does not exist.
	isEmpty ()
	Checks whether this folder contains any files or folders.
	delete ()
	Deletes this folder from the file system including anything in it.
	moveTo ($folder, $overwrite, $newName=NULL)
	Moves this folder into another directory (and optionally renames it).
	exists ()
	Whether this node already exists in the file system.
	residesIn (spunQ_IFolder $folder)
	Checks whether this file is in given folder or one of its subfolders.
	isReadable ()
	Whether the node is readable.
	getPath ()
	Returns the path pointing to the node.
	getPrettyPath ()
	Returns the most unique and human-readable path.
	getContainingFolder ()
	Returns the folder this node is residing in.
	getName ()
	Returns the name of this node, deprived of its path.
	getLastAccessTime ()
	Returns the time of last access of this node.
	getLastModificationTime ()
	Returns the time of last modification of this node.
	__toString ()
	Returns getPrettyPath().
Static Public Member Functions
static	current ()
	Provides the spunQ_Folder object of the folder calling file is in.
static	getByAlias ($alias, $throwException=true)
	Allows access to configured folders.
static	_init ()
	Initializes the class.
static	_shutdown ()
	Deletes all temporary folders.
static	get ($path)
	Factory method.
static	isHidden ($path)
	Whether a path indicates a hidden node (one that starts with a dot).
static	getSysTmp ()
	Gets the systems temporary folder.
static	createTemporaryFolder ()
	Creates a temporary folder.
static	pathIsAbsolute ($filePath)
	Tests if a givebn file path is absolute or relative.
static	prettifyPath ($path)
	Makes transformations to a path string to make it more readable.
Protected Attributes
	$path
	The path pointing to the node.
Private Member Functions
	getFilesWithAliasRecursiveImplementation ($path, $prefix, $suffixRegex, &$newest)
	Helper function for getFilesWithAliasRecursive().
Static Private Member Functions
static	getFilesRecursiveImplementation ($path, $suffixRegex, &$newest)
	Helper function for getFilesRecursive().
Static Private Attributes
static	$temporaryFolders = array()
	Array of temporary folders that will be removed on shutdown.