SnapDirectory Class Reference
[File Objects]

Wrapper class for Snap2 directories. More...

Inheritance diagram for SnapDirectory:

List of all members.

Public Member Functions

__construct ($id="")

canCreateDirectory ($shortName=false)

Determines whether a subdirectory can be created with the given shortname.

canCreateResource ($shortName=false, $contentType=SnapResource::TYPE_STDXML)

Determines whether a subresource can be created with the given shortname and type.

countContents ($constraint=array(), $limit=array(), $order=array())

Retrieves number of children of this directory, using constraints.

createDirectory ($shortName, $name="", $description="")

Creates a new subdirectory in this directory.

createResource ($shortName, $contentType=SnapResource::TYPE_STDXML, $name="", $description="")

Creates a resource in this directory.

listContents ($constraint=array(), $limit=array(), $order=array(), $count=false)

Retrieves array of objects representing the contents of this directory.

toCacheDump ()

Static Public Member Functions

static lookup ($path)

Retrieves a directory by path.

static retrieve ($id)

Retrieves a directory by ID.

Protected Member Functions

doDestroy ()

This method implements the directory-specific part of destroying a file.

loadMaxDirOrdinal ()

Loads the maximum directory ordinal for this directory.

loadMaxResOrdinal ()

Loads the maximum resource ordinal for this directory.

Detailed Description

Wrapper class for Snap2 directories.

A directory is a container for resources and other directories. It is a type of file (see SnapFile) and thus can be linked, unlinked, deleted, etc. It is important to note that you never create a SnapDirectory object directly. You will get them indirectly from factory methods in this class, or query methods, such as listContents().

Attributes:

id: directory ID
name: descriptivie name of directory
description: description of directory
created: creation date/time of directory
modified: date/time of last modification to directory metadata
canonParentId: ID of canonical parent directory
refCount: number of links to this directory, including canonical link

Fields:

maxDirOrdinal: maximum ordinal of any subdirectory in this directory
maxResOrdinal: maximum ordinal of any resource in this directory

Definition at line 26 of file SnapDirectory.php5.

Constructor & Destructor Documentation

SnapDirectory::__construct ( $ id = "" )

For internal use only.

Definition at line 31 of file SnapDirectory.php5.

Member Function Documentation

SnapDirectory::canCreateDirectory ( $ shortName = false )

Determines whether a subdirectory can be created with the given shortname.

In order for a subdirectory to be created, the following conditions must apply:

The shortname must consist solely of alphanumeric characters, underscores or dashes
There must be no other subdirectory with the provideed shortname
The logged in user must have the CreateDirectory permission set on this directory object

If you do not provide a shortname, then the first two checks will not be done. This is useful if you merely want to test the ability to create any subdirectories at all. Right now, it is equivalent to calling mayCreateDirectory() on the permission object belonging to this directory, but in the future, there may be other checks. It is best to use the can* methods whenever possible.

If a subdirectory cannot be created, this method returns false and sets the reason to a descriptive sentence. You can find this reason by calling getReason(). It does not generate errors directly.

Parameters:

$shortName

[string]: name of the new subdirectory, or false to ignore shortname check

Returns:: [boolean]: whether it is allowed/possible to create a subdirectory in this directory

Definition at line 254 of file SnapDirectory.php5.

References SnapDBI::freeResult(), and SnapObject::setReason().

Referenced by createDirectory().

SnapDirectory::canCreateResource	(	$	shortName = `false`,
		$	contentType = `SnapResource::TYPE_STDXML`
	)

Determines whether a subresource can be created with the given shortname and type.

In order for a subresource to be created, the following conditions must apply:

The shortname must consist solely of alphanumeric characters, underscores or dashes
There must be no other subresource with the provideed shortname
The content type must be one of the valid content types (see SnapResource for a list of these)
The logged in user must have the CreateDirectory permission set on this directory object

If you provide a shortname of false, then the first two checks will be skipped. If you provide no arguments, shortname defaults to false and the content type defaults to SnapResource::TYPE_STDXML and the first two checks will not be done. This is useful if you merely want to test the ability to create any subresources at all. Right now, it is equivalent to calling mayCreateResource() on the permission object belonging to this directory, but in the future, there may be other checks. It is best to use the can* methods whenever possible.

If a subresource cannot be created, this method returns false and sets the reason to a descriptive sentence. You can find this reason by calling getReason(). It does not generate errors directly.

Parameters:

	$shortName	[string]: name of the new subresource, or false to ignore shortname check
	$contentType	[int]: resource content type, defaults to SnapResource::TYPE_STDXML

Returns:: [boolean]: whether it is allowed/possible to create a subresource in this directory

Definition at line 314 of file SnapDirectory.php5.

References SnapDBI::freeResult(), SnapObject::getId(), SnapDBI::getNumRows(), SnapFile::getPermission(), SnapContent::isValidType(), SnapDBI::query(), and SnapObject::setReason().

Referenced by createResource().

SnapDirectory::countContents	(	$	constraint = `array()`,
		$	limit = `array()`,
		$	order = `array()`
	)

Retrieves number of children of this directory, using constraints.

See the documentation for listContents() for more on the parameters to this method

Parameters:

	$constraint	[array]: trim down results by conditions
	$limit	[array]: limit number of results by count and offset
	$order	[array]: sort results

Returns:: [integer]: number of results given constraints

Definition at line 636 of file SnapDirectory.php5.

References listContents().

SnapDirectory::createDirectory	(	$	shortName,
		$	name = `""`,
		$	description = `""`
	)

Creates a new subdirectory in this directory.

The subdirectory is created with the given metadata. You must, at the very least, specify a shortname, which is the name of the first and only link to the subdirectory. If you do not specifiy a regular name, the shortname will be used. The description field is more fully optional and if left blank, no default description will be provided. To create a directory, you must have CreateDirectory on this (the parent) directory. The new directory inherits all permissions from this directory automatically.

Parameters:

	$shortName	[string]: short name of new directory (name of first and only link)
	$name	[string]: regular, descriptive name of new directory; $shortName is used if $name is empty
	$description	[string]: description of directory

Returns:: [SnapDirectory]: the newly created subdirectory, or null on failure

Definition at line 366 of file SnapDirectory.php5.

References SnapDBI::cancelTransaction(), canCreateDirectory(), SnapObject::checkValid(), SnapDBI::commitTransaction(), SnapDirectoryGroupPermission::copy(), SnapDirectoryUserPermission::copy(), SnapObject::getId(), SnapDBI::getInsertId(), SnapObject::getReason(), SnapFile::mklink(), SnapCache::putById(), SnapDBI::query(), SObject::setError(), and SnapDBI::startTransaction().

SnapDirectory::createResource	(	$	shortName,
		$	contentType = `SnapResource::TYPE_STDXML`,
		$	name = `""`,
		$	description = `""`
	)

Creates a resource in this directory.

The resource is created with the given metadata. If the name is omitted, the short name is used as the name as well. Note that the content type parameter is 2nd, not 4th as in snap2.0. You must have the CreateResource permission on this directory to create a resource in it. All permissions from this directory are propagated to the new resource, except for those which only apply to directories

Parameters:

	$shortName	[string]: short name of resource
	$contentType	[integer]: resource content type (cannot be changed after resource creation)
	$name	[string]: descriptive name of resource; $shortName is used if this parameter is empty
	$description	[string]: description of resource

Returns:: [SnapResource]: new resource object, or null on failure

Definition at line 434 of file SnapDirectory.php5.

References SnapDBI::cancelTransaction(), canCreateResource(), SnapObject::checkValid(), SnapDBI::commitTransaction(), SnapResourceGroupPermission::copy(), SnapResourceUserPermission::copy(), SnapObject::getId(), SnapDBI::getInsertId(), SnapObject::getReason(), SnapFile::mklink(), SnapCache::putById(), SnapDBI::query(), SObject::setError(), and SnapDBI::startTransaction().

SnapDirectory::doDestroy ( ) [protected]

This method implements the directory-specific part of destroying a file.

For internal use only.

This method iterates over all the child files and deletes those that have only one parent (that is, this directory itself), and unlinks from this directory those children that have multiple parents. If a child is a directory, then it will recursively do the same thing when its delete() method is called.

Returns:: [boolean] always true (for now)

Reimplemented from SnapFile.

Definition at line 56 of file SnapDirectory.php5.

References SnapObject::getId(), SnapFile::getParents(), and listContents().

SnapDirectory::listContents	(	$	constraint = `array()`,
		$	limit = `array()`,
		$	order = `array()`,
		$	count = `false`
	)

Retrieves array of objects representing the contents of this directory.

This method allows you to trim down the result set and sort it, mostly arbitrarily. The first parameter can be an array that specifies constraints that are converted into a WHERE clause on the database query. See Guide to Database Constraints for more on how to specify a constraint array. The second parameter lets you limit the number of results. As a simple number, a 'LIMIT x' is appended to the query. If an array of two numbers is given, then the first number specifies the offset to start the resultset at and the second specifies the number of records after that. The final parameter specifies how to order the results. If the elements in the array are not associative, then they are passed directly to the ORDER BY clause as is. If they are associative, then the key specifies the column and the value specifies either ASC or DESC.

Parameters:

	$constraint	[array]: trim down results by conditions
	$limit	[array]: limit number of results by count and offset
	$order	[array]: sort results
	$count	[boolean]: if true, only return a count of objects in directory, rather than objects themselves

Returns:: [array]: array of SnapFile objects that are children of this directory and satisfy the given constraints; or null if there was an error or invalid parameter

Definition at line 501 of file SnapDirectory.php5.

References SnapResource::$ATTRIBUTES, SnapObject::checkValid(), SnapDBI::criteriaToString(), SnapDBI::freeResult(), SnapCache::getById(), SnapObject::getId(), SnapDBI::getRow(), SObject::getStaticError(), SnapDBI::limitToString(), SnapDBI::orderToString(), SnapCache::putById(), SnapCache::putByPath(), SnapDBI::query(), SObject::setError(), and SnapPermissionCache::warmCache().

Referenced by countContents(), and doDestroy().

SnapDirectory::loadMaxDirOrdinal ( ) [protected]

Loads the maximum directory ordinal for this directory.

For internal use only.

A maximum ordinal is calculated by querying the DirectoryLink table on the 'ordinal' column and finding the maximum using the SQL 'MAX()' function. This does not count the number of subdirectories in the directory, but instead gets the ordinal of the subdirectory with the highest ordinal that is in this directory (canonically or not). The reordering methods should update ordinals such that the maximum ordinal is also equal to the number of directories in the directory. If there is a bug, however, this may not be the case.

Returns:: [boolean] essentially whether the DB query went through

Definition at line 80 of file SnapDirectory.php5.

References SnapObject::getId(), SnapObject::getType(), SnapDBI::query(), SObject::setError(), and SnapCache::updateById().

SnapDirectory::loadMaxResOrdinal ( ) [protected]

Loads the maximum resource ordinal for this directory.

For internal use only.

See the description under loadMaxDirOrdinal() for more on what this means. This method does the same thing except that it does it on subresources instead of subdirectories.

Returns:: [boolean] essentially whether the DB query went through

Definition at line 100 of file SnapDirectory.php5.

References SnapObject::getId(), SnapObject::getType(), SnapDBI::query(), SObject::setError(), and SnapCache::updateById().

static SnapDirectory::lookup ( $ path ) [static]

Retrieves a directory by path.

Use this method to retrieve a directory if you know its path. You cannot instantiate a directory and have it populate via a path anyways, but don't try, or worse things will happen.

Parameters:

$path

[string]: path to directory (remember the trailing slash!)

Returns:: [SnapDirectory]: directory object pointed to by $path, or null on failure or invalid path

Reimplemented from SnapFile.

Definition at line 162 of file SnapDirectory.php5.

References Snap2::checkInit(), and SnapCache::getByPath().

Referenced by TKSDRResourceResultSet::bufferContributorIcons(), SnapObject::convertReference(), SnapFile::lookup(), Snap2::lookup(), TSD::setPermission(), and TSDBook::uploadCoverImage().

static SnapDirectory::retrieve ( $ id ) [static]

Retrieves a directory by ID.

Use this method to get a SnapDirectory object if you know the ID. Do not instantiate a SnapDirectory object directly, or bad things will happen.

Parameters:

$id

[integer]: ID of directory

Returns:: [SnapDirectory]: directory indicated by ID, or null if ID is invalid

Definition at line 128 of file SnapDirectory.php5.

References Snap2::checkInit(), SnapCache::getById(), SnapObject::getId(), and SnapCache::putById().

Referenced by SnapObject::convertReference(), Snap2::getDeletedDirectory(), SnapFile::getParent(), Snap2::getRootDirectory(), and SnapFile::loadCanonicalParent().

SnapDirectory::toCacheDump ( )

For internal use only.

Reimplemented from SnapObject.

Definition at line 39 of file SnapDirectory.php5.

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

snap2/objects/SnapDirectory.php5


Public Member Functions
	__construct ($id="")
	canCreateDirectory ($shortName=false)
	Determines whether a subdirectory can be created with the given shortname.
	canCreateResource ($shortName=false, $contentType=SnapResource::TYPE_STDXML)
	Determines whether a subresource can be created with the given shortname and type.
	countContents ($constraint=array(), $limit=array(), $order=array())
	Retrieves number of children of this directory, using constraints.
	createDirectory ($shortName, $name="", $description="")
	Creates a new subdirectory in this directory.
	createResource ($shortName, $contentType=SnapResource::TYPE_STDXML, $name="", $description="")
	Creates a resource in this directory.
	listContents ($constraint=array(), $limit=array(), $order=array(), $count=false)
	Retrieves array of objects representing the contents of this directory.
	toCacheDump ()
Static Public Member Functions
static	lookup ($path)
	Retrieves a directory by path.
static	retrieve ($id)
	Retrieves a directory by ID.
Protected Member Functions
	doDestroy ()
	This method implements the directory-specific part of destroying a file.
	loadMaxDirOrdinal ()
	Loads the maximum directory ordinal for this directory.
	loadMaxResOrdinal ()
	Loads the maximum resource ordinal for this directory.

SnapDirectory Class Reference [File Objects]

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

SnapDirectory Class Reference
[File Objects]