SnapFile Class Reference
[File Objects]

Implements most functionality for directories and resources. More...

Inheritance diagram for SnapFile:

[legend]

List of all members.

Public Member Functions
	__call ($name, $args)
	INSERT BRIEF DESCRIPTION HERE.
	addStylesheet ($pathOrObj)
	INSERT BRIEF DESCRIPTION HERE.
	delete ()
	Moves file to /DELETED/ directory.
	destroy ()
	Completely deletes file and children.
	getAllPaths ()
	INSERT BRIEF DESCRIPTION HERE.
	getCanonicalShortName ()
	Retrieves canonical short name of file.
	getOrdinal ($parent)
	Retrieves ordinal of file with respect to a given parent directory.
	getParent ($idx)
	Retrieves parent object for specified parent index.
	getParentCount ()
	Retrieves the number of parents this file has.
	getParents ()
	Retrieves directory IDs of all parents of this file.
	getPaths ($ref)
	INSERT BRIEF DESCRIPTION HERE.
	getPermission ()
	Retrieves SnapPermission object for this file.
	getShortName ($parent)
	Retrieves short name of file with respect to a given parent directory.
	getStylesheets ($onlyThis=false)
	INSERT BRIEF DESCRIPTION HERE.
	isCanonChildOf ($what)
	Alias of isChildOf($what, true).
	isChildOf ($what, $strict=false)
	Determines whether this file is a child of a given directory.
	linkTo ($dest, $shortName="")
	Creates new link to another directory.
	move ($newParent, $newName= '', $removeOldLink=false)
	Convenience method that "moves" file from one directory to another.
	removeStylesheets ($which=null)
	INSERT BRIEF DESCRIPTION HERE.
	renameAt ($parent, $newName)
	Changes the name of a link.
	reorderIn ($parent, $newOrdinal)
	Change the ordering of the file in a given directory.
	restore ($newParent= '', $newName= '')
	Restores a deleted file to normal tree.
	setCanonicalParent ($newParent)
	Changes which link is considered the canonical (primary) link.
	setDescription ($newDesc)
	Changes the description of the file.
	setName ($newName)
	Changes the "long" name of the file.
	unlinkFrom ($src)
	Removes existing link to this file.
Static Public Member Functions
static	lookup ($path)
	Perform path lookup for directory or resource.
Public Attributes
const	MOVE_BOTTOM
	set ordinal to max ordinal for parent (for reorderIn())
const	MOVE_DOWN
	set ordinal to one more than what it is now (for reorderIn())
const	MOVE_TOP
	set ordinal to 1 (for reorderIn())
const	MOVE_UP
	set ordinal to one less than what it is now (for reorderIn())

---

Detailed Description

Implements most functionality for directories and resources.

Directories and resources share a number of common attributes and behaviors. This class provides methods for managing those so that they do not need to be duplicated in SnapDirectory and SnapResource.

Notably, files have one or more parents and different names for the link to each parent. Files also have creation and modification times and a permission object associated with them. Almost all of the linkage maintenance for Snap2 happens in this class.

For every function that performs an action that modifies the object, there is a corresponding "can" method that will return whether the operation is allowed/possible. For example, the method to change the short name of a file is renameAt(). The corresponding "can" function is canRenameAt(), which takes the same arguments as renameAt() but doesn't actually perform the action, it just checks to see whether the action is possible. If an operation is not possible, the reason can be retrieved by calling getReason(). No developer error messsage will be displayed unless a true internal error occurred. The "can" methods are not documented because they are dynamically generated.

Fields:

• Parents: associative array of parent ID => parent object pairs
• Ordinals: associative array of parent ID => ordinal pairs
• shortNames: associative array of parent ID => short name pairs
• oldParentIds: associative array of parent ID => old parent ID (see documentation about deletion for more)
• canonicalPath: canonical path
• canonicalParent: SnapDirectory object for canonical parent link
• permission: SnapPermission object associated with this file
• metadata: SnapMetadata object associated with this file

---

Member Function Documentation

SnapFile::__call	(	$	name,
		$	args
	)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

	$name	[TYPE]: DESCRIPTION
	$args	[TYPE]: DESCRIPTION

Returns:

[TYPE]: RETURN DESCRIPTION

Reimplemented from SnapObject.

SnapFile::addStylesheet

(

$

pathOrObj

)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

$pathOrObj

[TYPE]: DESCRIPTION

Returns:

[TYPE]: RETURN DESCRIPTION

SnapFile::delete

(

)

Moves file to /DELETED/ directory.

This is a composite operation. All links to the file are removed, which causes the file to be put in the /DELETED/ directory. The file must have the AdminDirectory/AdminResource permission to be deleted.

Returns:

[boolean]: success or failure

SnapFile::destroy

(

)

Completely deletes file and children.

The file must have already been delete()'ed. To destroy a file, you must have the DESTROY privilege or the ADMIN privilege. If this file is a directory, then all children are unlinked from the directory. If that is the last link for any of the children, then they are deleted (but not destroyed). If the file is a resource, its versions are added to a global list of versions to be destroyed. Once the recursive destroy is complete, these versions are deleted all at once. This way, if the database deletion fails, versions won't have already been deleted, resulting in corruption and loss of data.

Returns:

[boolean]: success or failure

SnapFile::getAllPaths

(

)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:

[TYPE]: RETURN DESCRIPTION

SnapFile::getCanonicalShortName

(

)

Retrieves canonical short name of file.

The canonical short name is the name of the link to the canonical parent of the file

Returns:

[string]: canonical short name

SnapFile::getOrdinal

(

$

parent

)

Retrieves ordinal of file with respect to a given parent directory.

The parent can be specified as a path, or a numeric index of the parent (among the list of parents the file has), or a negated directory ID of the parent.

Parameters:

$parent

[mixed]: which parent directory to get the ordinal for

Returns:

[integer]: ordinal of file in given parent, or false if parent is invalid

SnapFile::getParent

(

$

idx

)

Retrieves parent object for specified parent index.

Parents can be described by index. The ordering of the parents is determined by the order they were added in and nothing else. Use ~:getParents% to get a list of parent IDs and indices. Use ~:getCanonicalParent% to get the canonical parent, in preference to using this method to do the same.

Parameters:

$idx

[integer]: index of parent to retrieve

Returns:

[SnapDirectory]: parent object for given index, or null if index is invalid

SnapFile::getParentCount

(

)

Retrieves the number of parents this file has.

Returns:

[integer]: number of parents file has

SnapFile::getParents

(

)

Retrieves directory IDs of all parents of this file.

Returns:

[array]: array of directory IDs, one for each parent of this file

SnapFile::getPaths

(

$

ref

)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

$ref

[TYPE]: DESCRIPTION

Returns:

[TYPE]: RETURN DESCRIPTION

SnapFile::getPermission

(

)

Retrieves SnapPermission object for this file.

Each file has one and only one SnapPermission% object associated with it, which is used to query and set permissions for that object. Use this method to get the SnapPermission object. Do NOT try to create a SnapPermission object directly, or bad things may/will happen!

Returns:

[SnapPermission]: permission object for this file

SnapFile::getShortName

(

$

parent

)

Retrieves short name of file with respect to a given parent directory.

The parent can be specified as a path, or a numeric index of the parent (among the list of parents the file has), or a negated directory ID of the parent. Call ~:getCanonicalShortname% to get the canonical short name of the file.

Parameters:

$parent

[mixed]: which parent directory to get short name for

Returns:

[string]: short name of file in given parent, or false if parent is invalid

SnapFile::getStylesheets

(

$

onlyThis = false

)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

$onlyThis

[TYPE]: DESCRIPTION

Returns:

[TYPE]: RETURN DESCRIPTION

SnapFile::isCanonChildOf

(

$

what

)

Alias of isChildOf($what, true).

Parameters:

$what

[mixed]: path or directory ID of ancestor

Returns:

[boolean]: whether this file is descendent of ancestor, false if not or on failure

SnapFile::isChildOf	(	$	what,
		$	strict = false
	)

Determines whether this file is a child of a given directory.

The method name is somewhat of a misnomer. It would be better to say "descendent" instead of "child". This file can be considered a "child" of another directory if it is a immediate child of that directory or one of its parents is considered a "child" of the specified directory. That is, this file must descend from the specified directory. If the $strict parameter is true, then every link followed must be a canonical link. So this file must be the canonical child of the specified directory, or canonical child of a directory which is itself the canonical child of the specified directory, etc.

Parameters:

	$what	[mixed]: path or directory ID to ancestor we are checking to see if this file is a child of
	$strict	[boolean]: whether we only consider canonical linkage when determining ancestry

Returns:

[boolean]: true if file is descendent of specified directory, false if not or if there is an error

SnapFile::linkTo	(	$	dest,
		$	shortName = ""
	)

Creates new link to another directory.

Links allow files to be in multiple directories at the same time without having to duplicate the file. This can be useful for grouping files into multiple taxonomies.

When a link is added, no checks are made to see if cycles are introduced. In general, cycles are okay. Care is taken when cascading permissions not to follow cycles. You need the ModDirectory/ModResource permission on this file, and ModDirectory on the destination directory.

Parameters:

	$dest	[mixed]: reference to directory to which the link will be made; the reference can be a path or a directory ID
	$shortName	[string]: name of the link; if empty, the canonical short name is used, which is simply the shortname for the link associated with the canonical parent

Returns:

[boolean]: success or failure

static SnapFile::lookup

(

$

path

)

[static]

Perform path lookup for directory or resource.

This method will interpret the path and retrieve either a directory or a resource, if it can.

Parameters:

$path

[string]: path to file

Returns:

[SnapFile]: file indicated by $path, or null if path is invalid or does not point to an existing file

Reimplemented in SnapDirectory, and SnapResource.

SnapFile::move	(	$	newParent,
		$	newName = '',
		$	removeOldLink = false
	)

Convenience method that "moves" file from one directory to another.

This is a composite operation. It basically creates a new link in the target directory, sets that link as the canonical parent, and optionally removes the old link, creating the effect of moving the file. Moving requires AdminDirectory on both the current parent and the new parent and AdminDirectory/AdminResource on this file.

Parameters:

	$newParent	[mixed]: path to new parent, or directory ID of new parent
	$newName	[string]: new short name in destination directory; if empty, will use the current canonical short name.
	$removeOldLink	[boolean]: whether to remove the link left behind in the old canonical parent directory

Returns:

[boolean]: success or failure

SnapFile::removeStylesheets

(

$

which = null

)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

$which

[TYPE]: DESCRIPTION

Returns:

[TYPE]: RETURN DESCRIPTION

SnapFile::renameAt	(	$	parent,
		$	newName
	)

Changes the name of a link.

The link name must be unique within the given parent directory, among both resources and directories. This allows path lookups to actually work. You must also have the ModDirectory/ModResource permission on this file and ModDirectory on the target to change the name of a link.

Parameters:

	$parent	[mixed]: reference to parent to rename link of; the reference may be the path to the parent, the index of the parent in the list of parents, or, if it is a negative integer, the directory ID of the parent (after being negated again).
	$newName	[string]: new short name for link

Returns:

[boolean]: success or failure

SnapFile::reorderIn	(	$	parent,
		$	newOrdinal
	)

Change the ordering of the file in a given directory.

Resources and directories can be given arbitrary ordering within a directory. If a file exists in multiple directories, it has a different ordinal for each of those directories that is not affected by its ordinals in other directories. This function requires that you specify the new ordinal of the file, but you can also use one of the four constants: MOVE_UP, MOVE_DOWN, MOVE_TOP, MOVE_BOTTOM to set the ordinal to one less, one greater than what it is, 1 or the current max for the directory, respectively. These constants are members of the SnapFile class, so you must prefix them with SnapFile::. You must have the ModDirectory/ModResource permission on the file and ModDirectory on the parent to reorder the file.

Parameters:

	$parent	[mixed]: parent reference describing which directory to change the order of this file in; can be path to parent, or integer indicating the index of the parent, or a negative integer indicating the parent's ID (negated).
	$newOrdinal	[integer]: new ordinal of file in the specified directory, or one of the four constants: MOVE_UP, MOVE_DOWN, MOVE_TOP, MOVE_BOTTOM

Returns:

[boolean]: success or failure

SnapFile::restore	(	$	newParent = '',
		$	newName = ''
	)

Restores a deleted file to normal tree.

You must have the RESTORE privilege or the ADMIN privilege to restore a file. By default files are restored to where they were before being deleted, and with the same name. You can pass additional parameters to this method to change where the file is restored to and what its name is, in case, for example, there already is a file with that name in the restoration directory. Note that any links that the file had before being deleted will NOT be restored as these are lost when the file is deleted.

Parameters:

	$newParent	[SnapDirectory]: directory into which to restore the file
	$newName	[string]: new short name of file

Returns:

[boolean]: success or failure

SnapFile::setCanonicalParent

(

$

newParent

)

Changes which link is considered the canonical (primary) link.

The canonical link/parent is used when generate paths and canonical shortnames. It does not have any relevance for permission cascades, or anything else. You must have AdminDirectory on both the new and old parent, and AdminDirectory/AdminResource on this file. The new parent must be an existing link.

Parameters:

$newParent

[mixed]: reference to parent to become new canonical parent; the reference may be the path to the parent, or the index of the parent in the list of parents, or, if it is a negative integer, the directory ID of the parent (after being negated again).

Returns:

[boolean]: success or failure

SnapFile::setDescription

(

$

newDesc

)

Changes the description of the file.

You must have the ModDirectory/ModResource permission on this file to change its description.

Parameters:

$newDesc

[string]: new description of the file

Returns:

[boolean]: success or failure

SnapFile::setName

(

$

newName

)

Changes the "long" name of the file.

You must have the ModDirectory/ModResource permission on this file to change its name.

Parameters:

$newName

[string]: new "long" name of the file

Returns:

[boolean]: success or failure

SnapFile::unlinkFrom

(

$

src

)

Removes existing link to this file.

If this is the last link to the file, the operation will abort. Use delete() instead. If the link is to the canonical parent, then the canonical parent will be changed to be the first remaining link. You must have AdminDirectory permission on the new canonical parent, or the operation will abort as well. In all cases, you need AdminDirectory on the parent and AdminDirectory/AdminResource on this file to perform the operation.

Parameters:

$src

[mixed]: reference to parent to remove link from; the reference may be the path to the parent, or the index of the parent in the list of parents. If the reference is negative it is treated as the directory ID of the parent (after being negated again).

Returns:

[boolean]: success or failure

---

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

• snap2/objects/SnapFile.php5