spunQ_SourceFolder Class Reference

A folder that can filter source files. More...

Inheritance diagram for spunQ_SourceFolder:

List of all members.

Public Member Functions

getModule ()

Gets the module this folder contains.

__construct ($path, $module)

Will construct $sourceRegex and $includeRegex if not created already.

getFolders ($includeHidden=true)

Overridden to provide spunQ_SourceFolder objects.

getSourceFiles ()

Gets all source files in this folder.

getNameToFileMapping (&$youngest, array &$toInclude)

Creates an array mapping type names to files.

getNameToFileMappingTest (&$youngest, array &$toInclude)

Unused function! This was another implementation for getNameToFileMapping() that was making use of the registered module files (see spunQ::registerMultipleClassFiles()).

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.

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 createSourceFolder ($path, $module)

Factory method.

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.

Static Public Attributes

static $typeSuffixes

File suffixes that indicate a source file.

static $includeSuffixes

File suffixes that indicate a source file.

Static Protected Member Functions

static isSourceFile ($file)

Checks if a file is a source file that should be automatically included.

static getTypeName ($file)

Gets the Type name as indicated by the file name.

Protected Attributes

$path

The path pointing to the node.

Static Private Member Functions

static getNameToFileMappingRecursive ($folder, $name, &$toInclude, &$mapping, &$youngest)

Will recursively crawl the file system to create a type to file mapping.

static getNameToFileMappingRecursiveWithoutIncluding ($folder, $name, &$mapping, &$youngest)

Same as getNameToFileMappingRecursive(), without including the files.

Private Attributes

$module

The module this folder contains.

Static Private Attributes

static $sourceRegex = NULL

A preg regex that will match source file names.

static $includeRegex = NULL

A preg regex that will match files to be included.

Detailed Description

A folder that can filter source files.

Definition at line 6 of file SourceFolder.class.php.

Constructor & Destructor Documentation

spunQ_SourceFolder::__construct	(	$	path,
		$	module
	)

Will construct $sourceRegex and $includeRegex if not created already.

Parameters:

	$path	The string path to the file.
	$module	The module this folder belongs to.

Definition at line 153 of file SourceFolder.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, inherited]

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, inherited]

Deletes all temporary folders.

Returns:: void

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

spunQ_Folder::assureExists ( ) [inherited]

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 ( ) [inherited]

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.

static spunQ_SourceFolder::createSourceFolder	(	$	path,
		$	module
	)			`[static]`

Factory method.

Parameters:

	$path	String containing a path to a folder.
	$module	The module this folder belongs to.

Returns:: spunQ_SourceFolder

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

spunQ_Folder::createTemporaryFile ( ) [inherited]

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, inherited]

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, inherited]

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 ( ) [inherited]

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, inherited]

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 ) [inherited]

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, inherited]`

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 ) [inherited]

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 ) [inherited]

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`
	)			`[inherited]`

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
	)			`[inherited]`

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.

spunQ_Folder::getFilesWithAliasRecursive	(	array $	suffixes,
		&$	newest,
		$	alias
	)			`[inherited]`

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::getFolder ( $ name ) [inherited]

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_SourceFolder::getFolders ( $ includeHidden = true )

Overridden to provide spunQ_SourceFolder objects.

Parameters:

$includeHidden

Whether hidden folders should be returned, too.

Returns:: array<spunQ_SourceFolder>

Reimplemented from spunQ_Folder.

Definition at line 179 of file SourceFolder.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_SourceFolder::getModule ( )

Gets the module this folder contains.

Returns:: string

Definition at line 144 of file SourceFolder.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_SourceFolder::getNameToFileMapping	(	&$	youngest,
		array &$	toInclude
	)

Creates an array mapping type names to files.

Parameters:

	$youngest	This out parameter will contain the last modification timestamp of the most recently modified file.
	$toInclude	Out parameter that will contain a list of files that need to be passed to spunQ::requireAll().

Returns:: array<string,string> Mapping type names to file paths.

Definition at line 209 of file SourceFolder.class.php.

static spunQ_SourceFolder::getNameToFileMappingRecursive	(	$	folder,
		$	name,
		&$	toInclude,
		&$	mapping,
		&$	youngest
	)			`[static, private]`

Will recursively crawl the file system to create a type to file mapping.

Required by getNameToFileMapping().

Parameters:

	$folder	The folder path currently being processed.
	$name	The name of the module currently being processed.
	$toInclude	Out-parameter containing the files that need to be included in this module (as defined by $includeSuffixes).
	$mapping	Out-parameter containing the desired mapping.
	$youngest	This out-parameter will contain the last modification timestamp of the most recently modified file.

Returns:: void The generated $mapping is an out-parameter.

Definition at line 89 of file SourceFolder.class.php.

static spunQ_SourceFolder::getNameToFileMappingRecursiveWithoutIncluding	(	$	folder,
		$	name,
		&$	mapping,
		&$	youngest
	)			`[static, private]`

Same as getNameToFileMappingRecursive(), without including the files.

Will be used for the spunQ module, since its files are included otherwise (see include.php). The same could be achieved by calling getNameToFileMappingRecursive() and discarding the $toInclude value.

Parameters:

	$folder	The folder path currently being processed.
	$name	The name of the module currently being processed.
	$mapping	Out-parameter containing the desired mapping.
	$youngest	This out-parameter will contain the last modification timestamp of the most recently modified file.

Returns:: void The generated $mapping is an out-parameter.

Definition at line 119 of file SourceFolder.class.php.

spunQ_SourceFolder::getNameToFileMappingTest	(	&$	youngest,
		array &$	toInclude
	)

Unused function! This was another implementation for getNameToFileMapping() that was making use of the registered module files (see spunQ::registerMultipleClassFiles()).

But it actually turned out to be slower than the current implementation. The function is left in nonetheless for future optimization attempts.

Definition at line 229 of file SourceFolder.class.php.

spunQ_Folder::getParent ( ) [inherited]

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 ) [inherited]

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.

spunQ_SourceFolder::getSourceFiles ( )

Gets all source files in this folder.

Returns:: array<spunQ_File>

Definition at line 191 of file SourceFolder.class.php.

static spunQ_Folder::getSysTmp ( ) [static, inherited]

Gets the systems temporary folder.

Returns:: spunQ_Folder

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

static spunQ_SourceFolder::getTypeName ( $ file ) [static, protected]

Gets the Type name as indicated by the file name.

Parameters:

$file

A string containing the path to a file.

Returns:: string The name of the type or false if the file is not a source file.

Definition at line 60 of file SourceFolder.class.php.

spunQ_Folder::isEmpty ( ) [inherited]

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, inherited]

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.

static spunQ_SourceFolder::isSourceFile ( $ file ) [static, protected]

Checks if a file is a source file that should be automatically included.

Parameters:

$file

A string containing the path to a file.

Returns:: boolean

Definition at line 50 of file SourceFolder.class.php.

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

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_SourceFolder::$includeRegex = NULL [static, private]

A preg regex that will match files to be included.

This variable is a cache, it will be initiated once required.

Type:: string

Definition at line 43 of file SourceFolder.class.php.

spunQ_SourceFolder::$includeSuffixes [static]

Initial value:

 array(
        'type.php',
        'class.php',
        'exception.php',
        'error.php',
        'interface.php',
        'service.php',
        'function.php'
    )

File suffixes that indicate a source file.

Type:: array<string>

Definition at line 21 of file SourceFolder.class.php.

spunQ_SourceFolder::$module [private]

The module this folder contains.

Type:: string

Definition at line 138 of file SourceFolder.class.php.

spunQ_FileNode::$path [protected, inherited]

The path pointing to the node.

string

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

spunQ_SourceFolder::$sourceRegex = NULL [static, private]

A preg regex that will match source file names.

This variable is a cache, it will be initiated once required.

Type:: string

Definition at line 36 of file SourceFolder.class.php.

spunQ_SourceFolder::$typeSuffixes [static]

Initial value:

 array(
        '.type.php',
        '.service.php'
    )

File suffixes that indicate a source file.

Type:: array<string>

Definition at line 12 of file SourceFolder.class.php.

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

SourceFolder.class.php


Public Member Functions
	getModule ()
	Gets the module this folder contains.
	__construct ($path, $module)
	Will construct $sourceRegex and $includeRegex if not created already.
	getFolders ($includeHidden=true)
	Overridden to provide spunQ_SourceFolder objects.
	getSourceFiles ()
	Gets all source files in this folder.
	getNameToFileMapping (&$youngest, array &$toInclude)
	Creates an array mapping type names to files.
	getNameToFileMappingTest (&$youngest, array &$toInclude)
	Unused function! This was another implementation for getNameToFileMapping() that was making use of the registered module files (see spunQ::registerMultipleClassFiles()).
	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.
	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	createSourceFolder ($path, $module)
	Factory method.
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.
Static Public Attributes
static	$typeSuffixes
	File suffixes that indicate a source file.
static	$includeSuffixes
	File suffixes that indicate a source file.
Static Protected Member Functions
static	isSourceFile ($file)
	Checks if a file is a source file that should be automatically included.
static	getTypeName ($file)
	Gets the Type name as indicated by the file name.
Protected Attributes
	$path
	The path pointing to the node.
Static Private Member Functions
static	getNameToFileMappingRecursive ($folder, $name, &$toInclude, &$mapping, &$youngest)
	Will recursively crawl the file system to create a type to file mapping.
static	getNameToFileMappingRecursiveWithoutIncluding ($folder, $name, &$mapping, &$youngest)
	Same as getNameToFileMappingRecursive(), without including the files.
Private Attributes
	$module
	The module this folder contains.
Static Private Attributes
static	$sourceRegex = NULL
	A preg regex that will match source file names.
static	$includeRegex = NULL
	A preg regex that will match files to be included.