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

__call ($m, $args)

INSERT BRIEF DESCRIPTION HERE.

__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.

convertAttrFromDB ($attr)

INSERT BRIEF DESCRIPTION HERE.

convertAttrToDB ($attr)

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.

getFunctionFromEntity ($entity)

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.

getListQuery ($criteria)

Build the query to perform at getList() request.

getUniqueAttributes ()

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

isValidObject ()

Check to see if this object is ready to commit.

lowercaseFirst ($string)

INSERT BRIEF DESCRIPTION HERE.

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.

setFunctionFromEntity ($entity)

INSERT BRIEF DESCRIPTION HERE.

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

INSERT BRIEF DESCRIPTION HERE.

unmarkForDeletion ()

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

Static Public Member Functions

static criteriaToString ($arr, $attributes)

Converts criteria array to a string.

static limitToString ($limit)

Converts limit array to a string.

static orderToString ($order, $attributes)

Converts order array to string.

Protected Member Functions

addTouchedValue ($key)

INSERT BRIEF DESCRIPTION HERE.

doreplace ($item)

INSERT BRIEF DESCRIPTION HERE.

getFailedString ($action)

INSERT BRIEF DESCRIPTION HERE.

getTouchedValues ()

INSERT BRIEF DESCRIPTION HERE.

preAppendEntity ($value)

INSERT BRIEF DESCRIPTION HERE.

resetTouchedValues ()

INSERT BRIEF DESCRIPTION HERE.

setEntity ($entity)

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

Private Attributes

$DBI

The DBI to use for this object's queries.

$entity

The name of the database entity this object should query.

$isMarkedForDeletion

Is the object marked to be deleted when it is committed?

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>

Definition at line 21 of file SModel.php5.

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.

Definition at line 42 of file SModel.php5.

References $DBI, lowercaseFirst(), populate(), reset(), setDBI(), and setEntity().

Member Function Documentation

SModel::__call	(	$	m,
		$	args
	)

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

	$m	[TYPE]: DESCRIPTION
	$args	[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 946 of file SModel.php5.

References getAttributes(), lowercaseFirst(), and SObject::setError().

SModel::addTouchedValue ( $ key ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$key

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1425 of file SModel.php5.

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.

Definition at line 370 of file SModel.php5.

References DBIHasNoError(), getAttributes(), getDBI(), getEntity(), SObject::getError(), getFailedString(), getFunctionFromEntity(), getUniqueAttributes(), isValidObject(), preAppendEntity(), SWATFunctions::safeSql(), SObject::setError(), and setFunctionFromEntity().

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

Definition at line 256 of file SModel.php5.

References DBIHasNoError(), getDBI(), SObject::getError(), getFailedString(), getFunctionFromEntity(), SWATFunctions::safeSql(), SObject::setError(), and setFunctionFromEntity().

SModel::convertAttrFromDB ( $ attr )

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$attr

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 644 of file SModel.php5.

SModel::convertAttrToDB ( $ attr )

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$attr

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 626 of file SModel.php5.

static SModel::criteriaToString	(	$	arr,
		$	attributes
	)			`[static]`

Converts criteria array to a string.

For internal use only.

See the SWAT Model2 documentation on the wiki for more about the structure of this array

Parameters:

	$arr	[array]: criteria array
	$attributes	[array]: list of attributes that can be used in criteria array

Returns:: [string]: SQL string to be appended as a WHERE clause (does not include 'WHERE', though)

Definition at line 1192 of file SModel.php5.

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

Definition at line 1162 of file SModel.php5.

References getDBI(), SObject::getError(), getFailedString(), and SObject::setError().

Referenced by commit(), commitForeign(), getListQuery(), and populate().

SModel::doreplace ( $ item ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$item

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 926 of file SModel.php5.

SModel::getAllAttributes ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 659 of file SModel.php5.

References getAttributes(), and getFunctionFromEntity().

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.

Definition at line 70 of file SModel.php5.

Referenced by __call(), commit(), getAllAttributes(), getListQuery(), populate(), reset(), and superGetList().

SModel::getByCriteria ( $ criteria )

(DEPRECATED)

INSERT FULL DESCRIPTION HERE

Parameters:

$criteria

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 905 of file SModel.php5.

SModel::getDBI ( )

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

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

Definition at line 1090 of file SModel.php5.

Referenced by commit(), commitForeign(), DBIHasNoError(), getListQuery(), and populate().

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.

Definition at line 1043 of file SModel.php5.

Referenced by commit(), getList(), getListQuery(), populate(), preAppendEntity(), and superGetList().

SModel::getFailedString ( $ action ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$action

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 612 of file SModel.php5.

Referenced by commit(), commitForeign(), DBIHasNoError(), getList(), getListQuery(), populate(), and superGetList().

SModel::getForeignKey ( )

INSERT BRIEF DESCRIPTION HERE.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 218 of file SModel.php5.

Referenced by populate().

SModel::getFunctionFromEntity ( $ entity )

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$entity

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1126 of file SModel.php5.

References $entity.

Referenced by commit(), commitForeign(), getAllAttributes(), and populate().

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

Definition at line 781 of file SModel.php5.

References getEntity(), getFailedString(), getListQuery(), getUniqueAttributes(), SObject::hasError(), SObject::setError(), and SObject::setPrettyError().

SModel::getListQuery ( $ criteria )

Build the query to perform at getList() request.

For internal use only.

Process a request and create an SQL query to get a list of objects of the same type/entity as this object. Run the query and return the result to getList().

Parameters:

$criteria

[array]: An array of criteria on which to populate an object

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 683 of file SModel.php5.

References DBIHasNoError(), getAttributes(), getDBI(), getEntity(), getFailedString(), getUniqueAttributes(), and SObject::setError().

Referenced by getList().

SModel::getTouchedValues ( ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1413 of file SModel.php5.

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.

Definition at line 85 of file SModel.php5.

Referenced by commit(), getList(), getListQuery(), populate(), and superGetList().

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

Definition at line 579 of file SModel.php5.

Referenced by commit().

static SModel::limitToString ( $ limit ) [static]

Converts limit array to a string.

For internal use only.

If limit is an array, the one or two elements are treated as the one or two arguments to the SQL 'LIMIT' qualifier. If limit is a number, then that single number is treated as the sole argument to the SQL 'LIMIT' qualifier.

Parameters:

$limit

[array]: limit array

Returns:: [string]: SQL for limit (including 'LIMIT')

Definition at line 1314 of file SModel.php5.

SModel::lowercaseFirst ( $ string )

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$string

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1145 of file SModel.php5.

Referenced by __call(), and __construct().

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.

Definition at line 1074 of file SModel.php5.

static SModel::orderToString	(	$	order,
		$	attributes
	)			`[static]`

Converts order array to string.

For internal use only.

If $order is array, then each element indicates another sort column. If element is associative, the key is treated as the attribute and the value must be either 'ASC' or 'DESC'. If $order is a string, it is used as is.

Parameters:

	$order	[mixed]: order array or string
	$attributes	[array]: array of attributes that can be used in order array

Returns:: [string]: SQL string for order (including 'ORDER BY');

Definition at line 1357 of file SModel.php5.

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

Definition at line 109 of file SModel.php5.

References DBIHasNoError(), getAttributes(), getDBI(), getEntity(), SObject::getError(), getFailedString(), getForeignKey(), getFunctionFromEntity(), getUniqueAttributes(), SObject::setError(), and setFunctionFromEntity().

Referenced by __construct().

SModel::preAppendEntity ( $ value ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$value

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 235 of file SModel.php5.

References getEntity().

Referenced by commit().

SModel::resetTouchedValues ( ) [protected]

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1402 of file SModel.php5.

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

Definition at line 1064 of file SModel.php5.

References $DBI.

Referenced by __construct().

SModel::setEntity ( $ entity ) [protected]

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

For internal use only.

Parameters:

$entity

[string]: The name of the database entity

Definition at line 1052 of file SModel.php5.

References $entity.

Referenced by SSurvey::__construct(), and __construct().

SModel::setFunctionFromEntity ( $ entity )

INSERT BRIEF DESCRIPTION HERE.

For internal use only.

INSERT FULL DESCRIPTION HERE

Parameters:

$entity

[TYPE]: DESCRIPTION

Returns:: [TYPE]: RETURN DESCRIPTION

Definition at line 1107 of file SModel.php5.

References $entity.

Referenced by commit(), commitForeign(), populate(), and reset().

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

Definition at line 854 of file SModel.php5.

References getAttributes(), getEntity(), getFailedString(), getUniqueAttributes(), and SObject::setError().

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

SWAT/model/SModel.php5


Public Member Functions
	__call ($m, $args)
	INSERT BRIEF DESCRIPTION HERE.
	__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.
	convertAttrFromDB ($attr)
	INSERT BRIEF DESCRIPTION HERE.
	convertAttrToDB ($attr)
	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.
	getFunctionFromEntity ($entity)
	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.
	getListQuery ($criteria)
	Build the query to perform at getList() request.
	getUniqueAttributes ()
	Get the list of unique attributes for this object (candidate keys).
	isValidObject ()
	Check to see if this object is ready to commit.
	lowercaseFirst ($string)
	INSERT BRIEF DESCRIPTION HERE.
	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.
	setFunctionFromEntity ($entity)
	INSERT BRIEF DESCRIPTION HERE.
	superGetList ($criteria, $order="", $limit="")
	INSERT BRIEF DESCRIPTION HERE.
	unmarkForDeletion ()
	If this object has been marked for deletion, clear that marking.
Static Public Member Functions
static	criteriaToString ($arr, $attributes)
	Converts criteria array to a string.
static	limitToString ($limit)
	Converts limit array to a string.
static	orderToString ($order, $attributes)
	Converts order array to string.
Protected Member Functions
	addTouchedValue ($key)
	INSERT BRIEF DESCRIPTION HERE.
	doreplace ($item)
	INSERT BRIEF DESCRIPTION HERE.
	getFailedString ($action)
	INSERT BRIEF DESCRIPTION HERE.
	getTouchedValues ()
	INSERT BRIEF DESCRIPTION HERE.
	preAppendEntity ($value)
	INSERT BRIEF DESCRIPTION HERE.
	resetTouchedValues ()
	INSERT BRIEF DESCRIPTION HERE.
	setEntity ($entity)
	Set the name of the database entity that this object will populate from/commit to.
Private Attributes
	$DBI
	The DBI to use for this object's queries.
	$entity
	The name of the database entity this object should query.
	$isMarkedForDeletion
	Is the object marked to be deleted when it is committed?