SnapObject Class Reference
[Core]

Base class for all non-static Snap objects. More...

Inheritance diagram for SnapObject:

List of all members.

Public Member Functions

__call ($name, $args)

__construct ($type, $fields, $attributes)

Base constructor for Snap objects.

__sleep ()

Puts all object information in the $__FOR_CACHE variable, in preparation for serialization.

__wakeup ()

Part of the "deserialization" process. Reinstates variable values for non-public variables.

getAttributes ()

Retrieves the names of all the object's attributes.

getFields ()

Retrieves the names of all the object's fields.

getId ()

Retrieves object ID.

getReason ()

Retrieves user-targetted error message.

getType ()

Retrieves the object type.

getValues ()

Retrieves values for all fields in the object.

isLoaded ($field)

Determines whether a field has been loaded.

isValid ()

Returns whether object is valid.

toCacheDump ()

Returns a string describing the object for cache dumps.

Static Public Member Functions

static dumpResults ($result)

Takes a resultset array from a database query and puts it into table form. Probably will be removed soon.

Public Attributes

$__FOR_CACHE

Protected Member Functions

checkValid ($operation="")

Checks validity of object.

get ($field)

Retrieves the value of a field.

populate ()

Loads core set of fields and attributes.

saveForCache ()

Override to alter behavior when serializing.

set ($field, $value)

Sets the value of a field.

setReason ($msg)

Sets user-targetted error message.

setSave ($field, $save)

Sets whether a field should be saved on serialization.

setValid ($valid)

Sets whether object should be considered valid.

unsetField ($field)

Removes value from a field and marks it as not loaded.

Static Protected Member Functions

static convertReference ($ref, $type)

Utility method to convert path, ID or object to Snap object.

Detailed Description

Base class for all non-static Snap objects.

This class essentially provides utility methods and features to make it easier to implement the derived classes. Most notably, it supports fields and attributes, as well as autoloader methods, so that objects can easily have lazy loading of database attributes and other fields, for performance reasons.

Definition at line 12 of file SnapObject.php5.

Constructor & Destructor Documentation

SnapObject::__construct	(	$	type,
		$	fields,
		$	attributes
	)

Base constructor for Snap objects.

For internal use only.

This constructor essentially is used to initialize the fields and attributes of the object, and set up the auto-loader methods. Derived classes will pass in class-relevant information here. If you don't want a field to be saved during serialization, call setSave() and set it to false for that field.

Parameters:

	$type	[string]: object type (usually also the name of the table in the database)
	$fields	[array]: an associative array of field names => loader callbacks for all of the fields of the objects, including, but not limited to DB attributes; if the loader callback is "true" (or anything other than a valid callback), the default loader "populate()" will be used.
	$attributes	[array]: flat array listing the names of database attributes for this object, if any

Definition at line 51 of file SnapObject.php5.

Member Function Documentation

SnapObject::__call	(	$	name,
		$	args
	)

For internal use only.

Auto-generates getXxx() methods for each field in the class, to be used by users, not internally.

Parameters:

	$name	[string]: name of dynamic method called
	$args	[array]: arguments passed to dynamic method call

Returns:: [mixed]: depends on the method call

Reimplemented in SnapFile, and SnapVersion.

Definition at line 213 of file SnapObject.php5.

References checkValid(), and SObject::setError().

SnapObject::__sleep ( )

Puts all object information in the $__FOR_CACHE variable, in preparation for serialization.

For internal use only.

Definition at line 463 of file SnapObject.php5.

References saveForCache().

SnapObject::__wakeup ( )

Part of the "deserialization" process. Reinstates variable values for non-public variables.

For internal use only.

Definition at line 473 of file SnapObject.php5.

SnapObject::checkValid ( $ operation = "" ) [protected]

Checks validity of object.

For internal use only.

Use this method at the beginning of every public API method and bail if this method returns false.

Parameters:

$operation

[string]: name of operation that was going to be performed (may be removed in the future!)

Returns:: [boolean]: whether object is valid

Definition at line 195 of file SnapObject.php5.

References SObject::setError().

static SnapObject::convertReference	(	$	ref,
		$	type
	)			`[static, protected]`

Utility method to convert path, ID or object to Snap object.

For internal use only.

This method will take a path or ID and retrieve an object for that path or ID. You must also specify the intended type of Snap object, e.g., 'Directory', etc. If the reference passed in is already an object, it is checked to see if it is of the correct type. The purpose of this method is to allow a user to pass anything "snappy" to a method and have the method ultimately get an object to work with.

Parameters:

	$ref	[mixed]: path, ID or object to convert
	$type	[string]: intended output object type; must be one of 'Directory', 'Resource', 'Version' or 'File'

Returns:: [object]: correct Snap object, or null on error (or if there is no object for reference)

Definition at line 365 of file SnapObject.php5.

References SnapVersion::lookup(), SnapResource::lookup(), SnapDirectory::lookup(), SnapVersion::retrieve(), SnapResource::retrieve(), and SnapDirectory::retrieve().

Referenced by SnapResource::_canCreateVersion().

static SnapObject::dumpResults ( $ result ) [static]

Takes a resultset array from a database query and puts it into table form. Probably will be removed soon.

For internal use only.

Definition at line 491 of file SnapObject.php5.

SnapObject::get ( $ field ) [protected]

Retrieves the value of a field.

For internal use only.

If the field is not loaded, the auto-loader is invoked for that field and the new value is returned.

Parameters:

$field

[string]: name of field to retrieve

Returns:: [mixed]: value of field, or null on failure (e.g., invalid field name)

Definition at line 76 of file SnapObject.php5.

SnapObject::getAttributes ( )

Retrieves the names of all the object's attributes.

Note that these attributes are also fields. For objects which do not have a direct database representation, there should be no attributes (e.g., SnapPermission).

Returns:: [array]: flat array of attribute names, or false if object is invalid

Definition at line 306 of file SnapObject.php5.

References checkValid().

Referenced by SnapFile::populate().

SnapObject::getFields ( )

Retrieves the names of all the object's fields.

Returns:: [array]: flat array of field names, or false if object is invalid

Definition at line 293 of file SnapObject.php5.

References checkValid().

SnapObject::getId ( )

Retrieves object ID.

All Snap objects should have an ID of some sort. For those objects which correspond to database entities, the ID will be the primary key of the row that the object represents. For those objects which do not correspond to database entities (such as SnapPermission), the ID still uniquely represents the object in some useful way.

Returns:: [mixed]: ID of object or false if object is invalid

Definition at line 269 of file SnapObject.php5.

References checkValid().

Referenced by SnapFile::_canMove(), SnapFile::_canSetCanonicalParent(), SnapDirectory::canCreateResource(), SnapFile::checkForCycles(), SnapPermission::commit(), SnapMetadata::commit(), SnapDirectory::createDirectory(), SnapDirectory::createResource(), SnapFile::destroy(), SnapDirectory::doDestroy(), SnapPermission::getCachedAccess(), SnapPermission::getGroupPermObject(), SnapPermission::getGroupPermObjects(), SnapPermission::getUserPermObject(), SnapDirectory::listContents(), SnapResource::loadActiveVersion(), SnapFile::loadCanonicalParent(), SnapFile::loadCanonicalPath(), SnapVersion::loadContentModule(), SnapResource::loadDevVersion(), SnapResource::loadLiveVersion(), SnapDirectory::loadMaxDirOrdinal(), SnapResource::loadMaxOrdinal(), SnapDirectory::loadMaxResOrdinal(), SnapFile::loadMetadata(), SnapFile::loadPermission(), SnapVersion::loadPrevVersion(), SnapVersion::loadResource(), SnapVersion::logAction(), SnapFile::mklink(), SnapVersion::populate(), SnapMetadata::populate(), SnapFile::populate(), SnapFile::restore(), SnapResource::retrieve(), and SnapDirectory::retrieve().

SnapObject::getReason ( )

Retrieves user-targetted error message.

This is used primarily by the _canXxx() methods to indicate why an operation could not be performed. To display an error message to the user, call this method.

Returns:: [string]: error message

Definition at line 346 of file SnapObject.php5.

Referenced by SnapPermission::commit(), SnapDirectory::createDirectory(), SnapDirectory::createResource(), SnapFile::destroy(), SnapFile::reorderIn(), SnapFile::restore(), SnapPermission::revokeGroup(), SnapPermission::revokeUser(), SnapPermission::setGroupAccess(), SnapFile::setName(), and SnapPermission::setUserAccess().

SnapObject::getType ( )

Retrieves the object type.

Returns:: [string]: object type

Definition at line 254 of file SnapObject.php5.

References checkValid().

Referenced by SnapFile::_canMove(), SnapFile::_canSetCanonicalParent(), SnapPermission::canChangePermission(), SnapFile::checkForCycles(), SnapPermission::commit(), SnapMetadata::commit(), SnapPermission::getGroupKey(), SnapPermission::getUserKey(), SnapResource::loadActiveVersion(), SnapFile::loadCanonicalParent(), SnapFile::loadCanonicalPath(), SnapVersion::loadContentModule(), SnapResource::loadDevVersion(), SnapResource::loadLiveVersion(), SnapDirectory::loadMaxDirOrdinal(), SnapResource::loadMaxOrdinal(), SnapDirectory::loadMaxResOrdinal(), SnapFile::loadMetadata(), SnapFile::loadPermission(), SnapVersion::loadPrevVersion(), SnapVersion::loadResource(), SnapPermission::mayDelete(), SnapPermission::mayLinkTo(), SnapPermission::mayUnlinkFrom(), SnapFile::mklink(), SnapVersion::populate(), SnapMetadata::populate(), SnapFile::populate(), SnapFile::restore(), and SnapFile::setName().

SnapObject::getValues ( )

Retrieves values for all fields in the object.

Note that this method will NOT autoload unloaded fields. If you want those values returned here, you must trigger an autoload by, e.g., calling getXxx() where "Xxx" is the name of the field that needs to be autoloaded.

Returns:: [array]: associative array of field name => value pairs or false if object is invalid

Definition at line 283 of file SnapObject.php5.

References checkValid().

SnapObject::isLoaded ( $ field )

Determines whether a field has been loaded.

Parameters:

$field

[string]: which field to check

Returns:: [boolean]: whether field has been auto-loaded yet, or false if field is invalid or object is invalid

Definition at line 241 of file SnapObject.php5.

References checkValid(), and SObject::setError().

SnapObject::isValid ( )

Returns whether object is valid.

See setValid() for more on what it means for an object to be valid

Returns:: [boolean]: whether object is valid

Definition at line 182 of file SnapObject.php5.

SnapObject::populate ( ) [abstract, protected]

Loads core set of fields and attributes.

For internal use only.

This method shouldn't be called directly, even within the API. It will be called by the auto-loader, if needed. One exception is in constructors, where an ID may be passed in to the constructor, and an auto-populate might be reasonable. This may become deprecated, though.

Returns:: [boolean]: whether the populate succeeded

Reimplemented in SnapFile, SnapMetadata, SnapVersion, and SnapPermission.

SnapObject::saveForCache ( ) [protected]

Override to alter behavior when serializing.

For internal use only.

In general, don't override this method. Put everything in fields and it should Just Work (TM).

Definition at line 446 of file SnapObject.php5.

Referenced by __sleep().

SnapObject::set	(	$	field,
		$	value
	)			`[protected]`

Sets the value of a field.

For internal use only.

In addition to setting the value of the field, the field is also marked as loaded, so a subsequent call to get() will not trigger an autoload.

Parameters:

	$field	[string]: name of field to set
	$value	[mixed]: new value for field

Returns:: [boolean]: success or failure

Definition at line 96 of file SnapObject.php5.

SnapObject::setReason ( $ msg ) [protected]

Sets user-targetted error message.

For internal use only.

Because setError and setError will show errors at the top of the page in debug mode, it is necessary to have some other mechanism to indicate user errors within the API and have them safely be retrievable outside the API or even within the API without resulting in a debug error message. Until SErrorManager is fixed to address this problem, all of the _canXxx() methods should use setReason() to indicate an error that would prevent the operation from succeeding.

Parameters:

$msg

[string]: error message

Definition at line 334 of file SnapObject.php5.

Referenced by SnapResource::_canCreateVersion(), SnapFile::_canMove(), SnapFile::_canSetCanonicalParent(), SnapResource::_canSetValidDate(), SnapPermission::canChangePermission(), SnapDirectory::canCreateDirectory(), and SnapDirectory::canCreateResource().

SnapObject::setSave	(	$	field,
		$	save
	)			`[protected]`

Sets whether a field should be saved on serialization.

For internal use only.

Serialization is only used if APC caching is enabled. You should not save fields that are object references or some other insignificant piece of data that can easily be regenerated in the future.

Parameters:

	$field	[string]: name of field
	$save	[boolean]: whether to save field on serialization

Returns:: [boolean]: success or failure

Definition at line 121 of file SnapObject.php5.

References checkValid(), and SObject::setError().

Referenced by SnapVersion::__construct(), SnapResource::__construct(), and SnapFile::__construct().

SnapObject::setValid ( $ valid ) [protected]

Sets whether object should be considered valid.

For internal use only.

An object should only be invalid if it does not correspond to something in the database (when it otherwise should) or if there is some other corruption in the object, such as a failed populate(). If an object is marked as not valid, then almost no public functions will succeed on the object, preventing the user from getting invalid data or performing operations that would lead to curruption. The checkValid() method is used to enforce this. Every public method should start with a call to it. Note also that when an object is marked as invalid, all values and other information are nullified.

Parameters:

$valid

[boolean]: whether object should be considered valid

Definition at line 165 of file SnapObject.php5.

Referenced by SnapPermission::__construct(), SnapPermission::populate(), SnapVersion::populate(), SnapMetadata::populate(), SnapFile::populate(), and SnapVersion::systemDestroy().

SnapObject::toCacheDump ( )

Returns a string describing the object for cache dumps.

For internal use only.

Reimplemented in SnapDirectory, SnapResource, and SnapVersion.

Definition at line 483 of file SnapObject.php5.

SnapObject::unsetField ( $ field ) [protected]

Removes value from a field and marks it as not loaded.

For internal use only.

Use this method to reset a field that might need to be re-auto-loaded in the future. Especially useful for when a write operation has been performed on the database, and objects need to reload their internal caches. Unset those fields, and then the fields will be lazily reloaded, if needed.

Parameters:

$field

[string]: name of field to unset

Returns:: [boolean]: success or failure

Definition at line 141 of file SnapObject.php5.

References checkValid(), and SObject::setError().

Member Data Documentation

SnapObject::$__FOR_CACHE

For internal use only.

This hack is needed for proper serialization of snap objects; don't spend too much time thinking about it ;)

Definition at line 35 of file SnapObject.php5.

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

snap2/core/SnapObject.php5


Public Member Functions
	__call ($name, $args)
	__construct ($type, $fields, $attributes)
	Base constructor for Snap objects.
	__sleep ()
	Puts all object information in the $__FOR_CACHE variable, in preparation for serialization.
	__wakeup ()
	Part of the "deserialization" process. Reinstates variable values for non-public variables.
	getAttributes ()
	Retrieves the names of all the object's attributes.
	getFields ()
	Retrieves the names of all the object's fields.
	getId ()
	Retrieves object ID.
	getReason ()
	Retrieves user-targetted error message.
	getType ()
	Retrieves the object type.
	getValues ()
	Retrieves values for all fields in the object.
	isLoaded ($field)
	Determines whether a field has been loaded.
	isValid ()
	Returns whether object is valid.
	toCacheDump ()
	Returns a string describing the object for cache dumps.
Static Public Member Functions
static	dumpResults ($result)
	Takes a resultset array from a database query and puts it into table form. Probably will be removed soon.
Public Attributes
	$__FOR_CACHE
Protected Member Functions
	checkValid ($operation="")
	Checks validity of object.
	get ($field)
	Retrieves the value of a field.
	populate ()
	Loads core set of fields and attributes.
	saveForCache ()
	Override to alter behavior when serializing.
	set ($field, $value)
	Sets the value of a field.
	setReason ($msg)
	Sets user-targetted error message.
	setSave ($field, $save)
	Sets whether a field should be saved on serialization.
	setValid ($valid)
	Sets whether object should be considered valid.
	unsetField ($field)
	Removes value from a field and marks it as not loaded.
Static Protected Member Functions
static	convertReference ($ref, $type)
	Utility method to convert path, ID or object to Snap object.

SnapObject Class Reference [Core]

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

SnapObject Class Reference
[Core]