SModel Class Reference

Allows an object-relational mapping between a PHP5 class and a row of a database entity. More...

Inheritance diagram for SModel:

List of all members.

Public Member Functions

__construct ($id="")

Create (and optionally populate) a new model object.

commit ()

Save this object to one row of its linked database entity.

commitForeign ($table, $unique, $attributes, $foreignKey)

INSERT BRIEF DESCRIPTION HERE.

DBIHasNoError ($function="<not specified>", $msg="")

INSERT BRIEF DESCRIPTION HERE.

getAllAttributes ()

INSERT BRIEF DESCRIPTION HERE.

getAttributes ()

Get the names of all attributes for this object/entity.

getByCriteria ($criteria)

(DEPRECATED)

getDBI ()

Get the DBI class this object is using as a database interface.

getEntity ()

Get the name of the database entity that this object will populate from/commit to.

getForeignKey ()

INSERT BRIEF DESCRIPTION HERE.

getList ($criteria="", $nullable=false)

Get a list of objects of this type from the database, based on a set of constraints.

getUniqueAttributes ()

Get the list of unique attributes for this object (candidate keys).

isValidObject ()

Check to see if this object is ready to commit.

markForDeletion ()

Mark this object to be deleted when it is next committed.

populate ($id="")

Populate this object from one row of its linked database entity.

reset ()

Set all attribute values to null. Remove 'marked for deletion' flag.

setDBI ($DBI)

Set the DBI class this object should use as a database interface.

superGetList ($criteria, $order="", $limit="")

INSERT BRIEF DESCRIPTION HERE.

unmarkForDeletion ()

If this object has been marked for deletion, clear that marking.

Detailed Description

Allows an object-relational mapping between a PHP5 class and a row of a database entity.

Extend this class to create objects that can easily be read from/write to the database.

In order to build your own SModel class, simply extend this class and implement the getAttributes() and getUniqueAttributes() functions in your subclass. Also set the entity in the constructor or implement getEntity() if you want to use a different entity name from the name of the class (SModel will lowercase the first letter of the class name).

To read from/write to the database, simply call populate() and commit() on your SModel objects. Also, SModel objects allow you to search for a list of objects of the same type using the getList() function.

Author:

Jonathan Stuart-Moore <jwsm@shodor.org> (2007)

Zhi Chen <zchen@shodor.org> (2007)

Joel Feiner <jfeiner@shodor.org>

Constructor & Destructor Documentation

SModel::__construct ( $ id = "" )

Create (and optionally populate) a new model object.

Create a new model object. Set the name of the database entity this object will query to the name of this class (but changing the first letter to lowercase).

If you pass in an id, the object will attempt to populate using that id number as the primary key.

Parameters:

$id

[int]: The object's primary key (optional)

Returns:: [bool]: true

Reimplemented in SSurvey.

Member Function Documentation

SModel::commit ( )

Save this object to one row of its linked database entity.

Check to see whether this object has a primary key. If not, attempt to insert a new row into the linked database entity for this object. If so, attempt to update the row specified by the primary key.

Copy all the relevant attributes, listed by this object's getAttributes() function, to the database row.

If we have just inserted a new row of the table, set this object's primary key to the id of the new primary key generated by the database insert.

Returns:: [bool]: True if the commit succeeded, false otherwise

Reimplemented in SGlobalUser.

SModel::commitForeign	(	$	table,
		$	unique,
		$	attributes,
		$	foreignKey
	)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

	$table	[TYPE]: DESCRIPTION
	$unique	[TYPE]: DESCRIPTION
	$attributes	[TYPE]: DESCRIPTION
	$foreignKey	[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

SModel::DBIHasNoError	(	$	function = `"<not specified>"`,
		$	msg = `""`
	)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

	$function	[TYPE]: DESCRIPTION
	$msg	[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

SModel::getAllAttributes ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

SModel::getAttributes ( )

Get the names of all attributes for this object/entity.

Return an array of all the instance variables for this object/entity that should be committed to the database when commit() is called on this object.

Returns:: [array]: The list of attribute names (as strings)

Reimplemented in CSERDUser, SEvent, SQuestion, SResponse, SSurvey, SGlobalUser, and SUser.

SModel::getByCriteria ( $ criteria )

(DEPRECATED)

INSERT FULL DESCRIPTION HERE

Parameters:

$criteria

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

SModel::getDBI ( )

Get the DBI class this object is using as a database interface.

Returns:: [DBI]: This object's DBI object

SModel::getEntity ( )

Get the name of the database entity that this object will populate from/commit to.

Returns:: [string]: The name of the database entity

Reimplemented in CSERDUser, and SSurvey.

SModel::getForeignKey ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

SModel::getList	(	$	criteria = `""`,
		$	nullable = `false`
	)

Get a list of objects of this type from the database, based on a set of constraints.

Search for a list of rows in this object's linked database entity, based on the constraints passed in. For each row found, create an object of the same type as this object. Return those objects as an array.

Parameters:

	$criteria	[array]: The search criteria
	$nullable	[TYPE]: DESCRIPTION

Returns:: [array]: An array of objects of the same type as this object, meeting the constraints

SModel::getUniqueAttributes ( )

Get the list of unique attributes for this object (candidate keys).

Return a list of the unique attributes (candidate keys) for this object. The first item in this list must be the primary key. But you should theoretically be able to populate on any attribute in this list.

For most objects, this function will return a list with one element -- the string 'id'

Returns:: [array]: The list of unique attribute names (as strings)

Reimplemented in CSERDUser, SEvent, SQuestion, SResponse, SSurvey, SGlobalUser, and SUser.

SModel::isValidObject ( )

Check to see if this object is ready to commit.

This function is called by commit() before the object is written to the database. You can implement this function in your subclass to put in place some checks that must be true before the object can be committed.

Returns:: [bool]: True if the object is ready to commit

SModel::markForDeletion ( )

Mark this object to be deleted when it is next committed.

This is a flag that you can set on the object so that, when you call commit() next, the row corresponding to this object will be deleted from the linked database entity.

SModel::populate ( $ id = "" )

Populate this object from one row of its linked database entity.

Lookup one row in the database based on the passed id/primary key value. If no value is passed in, check to see whether any of the other unique attributes are set on this object. If so, attempt to populate on those in the order they are listed by getUniqueAttributes().

Once we have found a row, select all the relevant attributes from that row, listed by this object's getAttributes() function. Then, copy the values from that row into this object's instance variables.

Parameters:

$id

[mixed]: A primary key value on which to populate this object

Returns:: [bool]: True if the populate succeeded, false otherwise

SModel::setDBI ( $ DBI )

Set the DBI class this object should use as a database interface.

Set the DBI class this object should use to run populate()/commit() queries. The DBI determines what database we are connected to.

Parameters:

$DBI

[DBI]: A DBI object

SModel::superGetList	(	$	criteria,
		$	order = `""`,
		$	limit = `""`
	)

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Parameters:

	$criteria	[TYPE]: DESCRIPTION
	$order	[TYPE]: DESCRIPTION
	$limit	[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

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

SWAT/model/SModel.php5


Public Member Functions
	__construct ($id="")
	Create (and optionally populate) a new model object.
	commit ()
	Save this object to one row of its linked database entity.
	commitForeign ($table, $unique, $attributes, $foreignKey)
	INSERT BRIEF DESCRIPTION HERE.
	DBIHasNoError ($function="<not specified>", $msg="")
	INSERT BRIEF DESCRIPTION HERE.
	getAllAttributes ()
	INSERT BRIEF DESCRIPTION HERE.
	getAttributes ()
	Get the names of all attributes for this object/entity.
	getByCriteria ($criteria)
	(DEPRECATED)
	getDBI ()
	Get the DBI class this object is using as a database interface.
	getEntity ()
	Get the name of the database entity that this object will populate from/commit to.
	getForeignKey ()
	INSERT BRIEF DESCRIPTION HERE.
	getList ($criteria="", $nullable=false)
	Get a list of objects of this type from the database, based on a set of constraints.
	getUniqueAttributes ()
	Get the list of unique attributes for this object (candidate keys).
	isValidObject ()
	Check to see if this object is ready to commit.
	markForDeletion ()
	Mark this object to be deleted when it is next committed.
	populate ($id="")
	Populate this object from one row of its linked database entity.
	reset ()
	Set all attribute values to null. Remove 'marked for deletion' flag.
	setDBI ($DBI)
	Set the DBI class this object should use as a database interface.
	superGetList ($criteria, $order="", $limit="")
	INSERT BRIEF DESCRIPTION HERE.
	unmarkForDeletion ()
	If this object has been marked for deletion, clear that marking.