SnapDirectory Class Reference
[File Objects]

Wrapper class for Snap2 directories. More...

Inheritance diagram for SnapDirectory:

[legend]

List of all members.

Public Member Functions
	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.
Static Public Member Functions
static	lookup ($path)
	Retrieves a directory by path.
static	retrieve ($id)
	Retrieves a directory by ID.

---

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

---

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:

1. The shortname must consist solely of alphanumeric characters, underscores or dashes
2. There must be no other subdirectory with the provideed shortname
3. 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

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:

1. The shortname must consist solely of alphanumeric characters, underscores or dashes
2. There must be no other subresource with the provideed shortname
3. The content type must be one of the valid content types (see SnapResource for a list of these)
4. 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

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

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

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

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

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.

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

---

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

• snap2/objects/SnapDirectory.php5