SnapPermission Class Reference
[Permissions Management Objects]

Primary interface for querying and managing permissions associated with Snap2 objects. More...

Inheritance diagram for SnapPermission:

[legend]

List of all members.

Public Member Functions
	cancel ()
	Cancels permission changes.
	canChangePermission ()
	Returns whether current user can actually change permissions on our file.
	commit ($cascade=false)
	Commit permission changes.
	getGroupAccess ($cap, $gid)
	Gets group access for a given group.
	getGroupsAccess ($cap, $uid= '')
	Get group-level access for all groups a user belongs to.
	getUserAccess ($cap, $uid= '')
	Gets effective access just considering the user-level permissions for this file.
	has ($cap, $uid= '')
	Returns whether user has a given permission set on our file.
	hasEx ($cap, $uid= '')
	Advanced form of has() that returns the derivation of the user's access.
	mayApproveForDev ($uid= '')
	Whether user can approve a version for dev.
	mayApproveForLive ($uid= '')
	Whether user can approve a version for live.
	mayChangeMetadata ($uid= '')
	Whether user has permission to change the metdata of a file.
	mayChangePermission ($uid= '')
	Returns whether specified user has permission to change permissions on our file.
	mayCreateDirectory ($uid= '')
	Whether user has permission to create a directory in our directory.
	mayCreateResource ($uid= '')
	Whether user has permission to create a resource in our directory.
	mayCreateVersion ($uid= '')
	Whether user has permission to create a version in our resource.
	mayDefunct ($status, $uid= '')
	Whether user can mark a version as defunct.
	mayDelete ($uid= '')
	Whether user has permission to delete our file.
	mayDeny ($uid= '')
	Whether user can return a Pending version to In Progress.
	mayDestroy ($uid= '')
	Whether user has permission to destroy our file from /DELETED/.
	mayDestroyVersion ($uid= '')
	Whether user can destroy (permanently delete) a version.
	mayLinkTo ($to, $uid= '')
	Whether user has permission to create link.
	mayMove ($newParent, $uid= '')
	Whether user has permission to move our file.
	mayRenameAt ($at, $uid= '')
	Whether user has permission to rename a link.
	mayRenameFiles ($uid= '')
	Determines whether files may be renamed in our directory.
	mayReorderFiles ($uid= '')
	Determines whether files may be reordered in our directory.
	mayReorderIn ($in, $uid= '')
	Whether user has permission to reorder a file in a directory.
	mayRestore ($uid= '')
	Whether user has permission to restore our file from /DELETED/.
	maySetCanonicalParent ($newParent, $uid= '')
	Whether user has permission to change our file's canonical path.
	maySteal ($uid= '')
	Whether user can grab ownership of a version that is In Progress.
	maySubmit ($uid= '')
	Whether user can submit a version (make it Pending).
	mayUnlinkFrom ($from, $uid= '')
	Whether user has permission to remove link.
	mayUpdate ($uid= '')
	Whether user can modify the content (update) a version.
	revokeGroup ($gid)
	Revoke all access to this file for given group.
	revokeUser ($uid= '')
	Revoke all access to this file for given user.
	setGroupAccess ($cap, $access, $gid)
	Grants or revokes a given permissions for a given group on our file.
	setUserAccess ($cap, $access, $uid= '')
	Grants or revokes a given permissions for a given user on our file.
Static Public Member Functions
static	getCapabilities ($type)
	Get a list of capabilities (permissions) that apply to a given file type.
static	getCapabilityDescriptions ($type)
	Get a list of capability descriptions for capabilities that apply to a given file type.
static	grantPrivilege ($role, $uid)
	Gives a user a privilege.
static	isSpecialUser ($role, $uid= '')
	Returns whether given user has a given privilege.
static	listSpecialUsers ()
	Returns list of all users with one or more privileges.
static	revokePrivilege ($role, $uid)
	Revoke privilege from user.
Public Attributes
const	ACCESS_ADMIN
	Permission granted via the ADMIN privilege.
const	ACCESS_DEFAULT_DENY
	Permission denied by default (no explicit ALLOWs or DENYs).
const	ACCESS_DESTROY
	Permission granted via the DESTROY privilege (not used).
const	ACCESS_GROUP_ALLOW
	Permission granted by a group with ALLOW set.
const	ACCESS_GROUP_DENY
	Permission denied by a group with DENY set.
const	ACCESS_RESTORE
	Permission granted via the RESTORE privilege (not used).
const	ACCESS_USER_ALLOW
	Permission granted for the user by explicit ALLOW.
const	ACCESS_USER_DENY
	Permission denied for the user by explicit DENY.
const	CAP_ALLOW
	Explicit allow of capability.
const	CAP_DEFAULT
	No explicit granting or denying of capability.
const	CAP_DENY
	Explicity deny of capability.
const	USER_ADMIN
	ADMIN privilege constant
const	USER_DESTROY
	DESTROY privilege constant
const	USER_RESTORE
	RESTORE privilege constant

---

Detailed Description

Primary interface for querying and managing permissions associated with Snap2 objects.

As an instance, this class represents the permissions associated with a single file (directory or resource). It also has class (static) methods for dealing with privileges, which are global permissions that are associated with users, but not with objects, and always override plain object-based permissions.

Fields:

• file: File which this permission object is associated with
• fileType: File's type ('Directory' or 'Resource')
• permObjects: Array of database permission objects (not needed to be used outside the API)
• parties: Array of users who have permissions on this object's file

---

Member Function Documentation

SnapPermission::cancel

(

)

Cancels permission changes.

This will nullify any permission changes initiated with setAccess() or revoke().

SnapPermission::canChangePermission

(

)

Returns whether current user can actually change permissions on our file.

The current user must have the necessary permissions on the file, but the file also cannot be a deleted file or a root directory.

Returns:

[boolean]: whether user can change permissions on this file

SnapPermission::commit

(

$

cascade = false

)

Commit permission changes.

All permission changes with setUserAccess() (or setGroupAccess()) and revokeUser() (or revokeGroup()) are queued until this method is called. If you pass in true for the $cascade parameter, then the permission changes will be applied to all child files of this file. Any permissions that were not changed by the set*Access() or revoke*() calls will not be modified in any way.

Parameters:

$cascade

[boolean]: whether to apply changes to child files

Returns:

[boolean]: success or failure

static SnapPermission::getCapabilities

(

$

type

)

[static]

Get a list of capabilities (permissions) that apply to a given file type.

Parameters:

$type

[string]: one of 'File', 'Directory', 'Resource', 'DirOnly', 'ResOnly', 'Version'

Returns:

[array]: associative array of capability ID => capability name entries

static SnapPermission::getCapabilityDescriptions

(

$

type

)

[static]

Get a list of capability descriptions for capabilities that apply to a given file type.

Parameters:

$type

[string]: one of 'File', 'Directory', 'Resource', 'DirOnly', 'ResOnly', 'Version'

Returns:

[array]: associative array of capability ID => capability description entries

SnapPermission::getGroupAccess	(	$	cap,
		$	gid
	)

Gets group access for a given group.

Parameters:

	$cap	[string]: name of capability
	$gid	[int]: group ID of group

Returns:

[int]: one of ACCESS_GROUP_ALLOW, ACCESS_GROUP_DENY or ACCESS_DEFAULT_DENY

SnapPermission::getGroupsAccess	(	$	cap,
		$	uid = ''
	)

Get group-level access for all groups a user belongs to.

This method checks all of the groups a user belongs to and determines the highest level of access granted among all the groups. The rankings are: default deny, allow and deny. If the highest any group has set for the given capability is default, then default deny will be returned. If the highest of any group is allow, then allow will be returned, etc. Note that deny is higher than allow. Thus, a single deny can override any number of allows.

Parameters:

	$cap	[string]: name of capability
	$uid	[int]: user ID of user whose groups are to be checked (defaults to current user)

Returns:

[int]: one of ACCESS_GROUP_ALLOW, ACCESS_GROUP_DENY or ACCESS_DEFAULT_DENY

SnapPermission::getUserAccess	(	$	cap,
		$	uid = ''
	)

Gets effective access just considering the user-level permissions for this file.

The user's effective access is computed only by looking at permissions set for the user on this file. Groups are ignored. Possible return values are ACCESS_DEFAULT_DENY.

static SnapPermission::grantPrivilege	(	$	role,
		$	uid
	)			[static]

Gives a user a privilege.

You must have the ADMIN privilege to grant a privilege to another user. If you have the ADMIN privilege you can also grant yourself additional privileges.

Parameters:

	$role	[int]: privilege to grant (one of the USER_* constants)
	$uid	[int]: user ID of user to grant privilege to

Returns:

[boolean]: success or failure

SnapPermission::has	(	$	cap,
		$	uid = ''
	)

Returns whether user has a given permission set on our file.

Parameters:

	$cap	[string]: name of permission we are querying for
	$uid	[int]: user ID of user whose permissions we are checking, defaults to current user

Returns:

[boolean]: whether user has $cap on our file

SnapPermission::hasEx	(	$	cap,
		$	uid = ''
	)

Advanced form of has() that returns the derivation of the user's access.

A user can "have" a permission by having it literally set on our file, or it can have it via having the ADMIN privilege. This method returns one of the ACCESS_* constants that indicates whether the user has a permission because they have ADMIN or because it is actually set (or unset) on our file either for the user, or one of the groups the user belongs to.

Parameters:

	$cap	[string]: permission to check for
	$uid	[int]: user ID of user whose permission we are checking

Returns:

[array]: first element is one of the ACCESS_* constants and the second is the group name if one of the groups generated the effective access; or two false's if an error occurred

static SnapPermission::isSpecialUser	(	$	role,
		$	uid = ''
	)			[static]

Returns whether given user has a given privilege.

Parameters:

	$role	[int]: privilege to check for (one of the USER_* constants)
	$uid	[int]: user ID of user to check for, defaults to current user

Returns:

[boolean]: whether user has specified privilege

static SnapPermission::listSpecialUsers

(

)

[static]

Returns list of all users with one or more privileges.

Returns:

[array]: list of users with privileges

SnapPermission::mayApproveForDev

(

$

uid = ''

)

Whether user can approve a version for dev.

Checks the AppoveVersionDev permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayApproveForLive

(

$

uid = ''

)

Whether user can approve a version for live.

Checks the ApproveVersionLive permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayChangeMetadata

(

$

uid = ''

)

Whether user has permission to change the metdata of a file.

Checks the ChangeFileMetadata permission. Changing metadata includes changing the name (not short name) and description of a file, as well as the valid date of a resource.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayChangePermission

(

$

uid = ''

)

Returns whether specified user has permission to change permissions on our file.

Parameters:

$uid

[int]: user ID of user, defaults to current user

Returns:

[boolean]: whether user has privilege or permission

SnapPermission::mayCreateDirectory

(

$

uid = ''

)

Whether user has permission to create a directory in our directory.

Checks the CreateDirectory permission.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayCreateResource

(

$

uid = ''

)

Whether user has permission to create a resource in our directory.

Checks the CreateResource permission.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayCreateVersion

(

$

uid = ''

)

Whether user has permission to create a version in our resource.

Checks the CreateVersion permission.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayDefunct	(	$	status,
		$	uid = ''
	)

Whether user can mark a version as defunct.

Checks the DefunctVersion permission on our resource. The user must also have the following permissions, depending on the state of the version:

• STATUS_PRIVATE: UpdateVersion
• STATUS_PENDING: SubmitVersion
• STATUS_DEV: ApproveVersionDev
• STATUS_LIVE: ApproveVersionLive

Parameters:

	$status	[int]: status of version that is to be defuncted
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayDelete

(

$

uid = ''

)

Whether user has permission to delete our file.

Checks for DeleteDirectory/DeleteResource on our file.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayDeny

(

$

uid = ''

)

Whether user can return a Pending version to In Progress.

Checks the DenyVersion permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayDestroy

(

$

uid = ''

)

Whether user has permission to destroy our file from /DELETED/.

Only checks if the user has the DESTROY or ADMIN privilege.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayDestroyVersion

(

$

uid = ''

)

Whether user can destroy (permanently delete) a version.

Checks the DestroyVersion permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayLinkTo	(	$	to,
		$	uid = ''
	)

Whether user has permission to create link.

Note: this only checks the permissions on $to, not our file. It checks for CreateDirectory/CreateResource on $to.

Parameters:

	$to	[mixed]: Snap reference to directory in which new link will be created
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayMove	(	$	newParent,
		$	uid = ''
	)

Whether user has permission to move our file.

Note: this only checks the permissions on $newParent and the current parent, not our file. Currently, this method just calls maySetCanonicalParent(). That may change in the future, so do not depend on this behavior.

Parameters:

	$newParent	[mixed]: Snap reference to directory to which our file is to be moved
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayRenameAt	(	$	at,
		$	uid = ''
	)

Whether user has permission to rename a link.

Note: this only checks the permissions on $at, not our file. It checks for RenameFile on $at.

Parameters:

	$at	[mixed]: Snap reference to directory in which link will be renamed
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayRenameFiles

(

$

uid = ''

)

Determines whether files may be renamed in our directory.

This function differs from mayRenameAt() in that it is called on the parent and determines whether files can be renamed in the parent, instead of whether the file itself can be renamed in one of its parents. The same permission, RenameFile is checked, this time on our file.

Parameters:

$uid

[int]: user ID of user whose permissions are to be checked; defaults to current user

Returns:

[boolean]: whether operation can be performed

SnapPermission::mayReorderFiles

(

$

uid = ''

)

Determines whether files may be reordered in our directory.

This function differs from mayReorderIn() in that it is called on the parent and determines whether files can be reordered in the parent, instead of whether the file itself can be reordered in one of its parents. The same permission, ReorderFile is checked, this time on our file.

Parameters:

$uid

[int]: user ID of user whose permissions are to be checked; defaults to current user

Returns:

[boolean]: whether operation can be performed

SnapPermission::mayReorderIn	(	$	in,
		$	uid = ''
	)

Whether user has permission to reorder a file in a directory.

Note: this only checks the permissions on $in, not our file. It checks for ReorderFile on $in.

Parameters:

	$in	[mixed]: Snap reference to directory in which file will be reordered
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayRestore

(

$

uid = ''

)

Whether user has permission to restore our file from /DELETED/.

Only checks if the user has the RESTORE or ADMIN privilege.

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::maySetCanonicalParent	(	$	newParent,
		$	uid = ''
	)

Whether user has permission to change our file's canonical path.

Note: this only checks the permissions on $newParent and the current parent, not our file. It checks for MoveFile on both the old and new parent.

Parameters:

	$newParent	[mixed]: Snap reference to directory which will become the new parent of our file
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::maySteal

(

$

uid = ''

)

Whether user can grab ownership of a version that is In Progress.

Checks the StealVersion permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::maySubmit

(

$

uid = ''

)

Whether user can submit a version (make it Pending).

Checks the SubmitVersion permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayUnlinkFrom	(	$	from,
		$	uid = ''
	)

Whether user has permission to remove link.

Note: this only checks the permissions on $from, not our file. It checks for DeleteDirectory/DeleteResource on $from.

Parameters:

	$from	[mixed]: Snap reference to directory in which old link will be removed
	$uid	[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::mayUpdate

(

$

uid = ''

)

Whether user can modify the content (update) a version.

Checks the UpdateVersion permission on our resource

Parameters:

$uid

[int]: user ID of user whose permission we are checking; defaults to current user

Returns:

[boolean]: whether user has permission to perform the operation

SnapPermission::revokeGroup

(

$

gid

)

Revoke all access to this file for given group.

You must have ChangeDirectoryPermission or ChangeResourcePermission on the file to revoke permissions. The ADMIN privilege will also suffice.

Parameters:

$gid

[int]: group ID of group whose access we are revoking

Returns:

[boolean]: success or failure

static SnapPermission::revokePrivilege	(	$	role,
		$	uid
	)			[static]

Revoke privilege from user.

You must have the ADMIN privilege to revoke privileges from users. You cannot revoke the ADMIN privilege from yourself. This is to prevent the situation where no user has the ADMIN privilege.

Parameters:

	$role	[int]: privilege to revoke (one of the USER_* constants)
	$uid	[int]: user ID of user to revoke privilege from

Returns:

[boolean]: success or failure

SnapPermission::revokeUser

(

$

uid = ''

)

Revoke all access to this file for given user.

You must have ChangeDirectoryPermission or ChangeResourcePermission on the file to revoke permissions. The ADMIN privilege will also suffice.

Parameters:

$uid

[int]: user ID of user whose access we are revoking, defaults to current user

Returns:

[boolean]: success or failure

SnapPermission::setGroupAccess	(	$	cap,
		$	access,
		$	gid
	)

Grants or revokes a given permissions for a given group on our file.

You must have ChangeDirectoryPermission or ChangeResourcePermission on this file to change its permissions. The ADMIN privilege will also suffice.

Parameters:

	$cap	[string]: name of permission to change
	$access	[boolean]: whether to grant or revoke permission
	$gid	[int]: group ID of group to change permission for

Returns:

[boolean]: success or failure

SnapPermission::setUserAccess	(	$	cap,
		$	access,
		$	uid = ''
	)

Grants or revokes a given permissions for a given user on our file.

You must have ChangeDirectoryPermission or ChangeResourcePermission on this file to change its permissions. The ADMIN privilege will also suffice.

Parameters:

	$cap	[string]: name of permission to change
	$access	[boolean]: whether to grant or revoke permission
	$uid	[int]: user ID of user to change permission for, defaults to current user

Returns:

[boolean]: success or failure

---

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

• snap2/perm/SnapPermission.php5