SDatabaseModel Class Reference
[Database Objects]

A generic model object that is populated/committed to a database. More...

Inheritance diagram for SDatabaseModel:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 commit ($updateObj=false)
 Save this object's attributes to a record in the database.
 copy ($asNew=false)
 Attempts to make a copy of this object.
 fromDB ($rep)
 Populate this object based on a link or representation stored in a foreign database field.
 getConstraintForPrimaryKey ($skipStorageCheck=false)
 Get a constraints array that uniquely specifies this object by its primary key.
 getFormatted ($field, $format)
 Retrieves a DATE/TIME field and formats it.
 getPrimaryKey ()
 Retrieves primary key attribute name for this object.
 getTableName ()
 Retrieves name of table this object represents.
 getXML ($options=array())
 Overridden getXML() more specific for database classes.
 isDatabaseAttribute ($attrName)
 Determines if given attribute is one that should go into the database.
 populate ($constraints, $multi=false)
 Populate this object's attributes from a record in the database.
 populateFromResults ($results)
 Populates this object from query results.
 populateFromResultsMulti ($results, $mapping=null, $as=null)
 Populates this object from query results.
 setFormatted ($field, $newValue)
 Updates a DATE/TIME field and formats according to what DB requires.
 toDB ()
 Provide a link to or representation of this object for storage in a foreign database field.

Static Public Member Functions

static isDatabaseAttributeStatic ($info)
 Determines if a given attribute is one that should go into the database.

Protected Member Functions

 onDelete ()
 Callback that is invoked during a DELETE operation.
 onDeleteFinish ()
 Callback that is invoked after a DELETE operation.
 onInsert ($what)
 Callback that is invoked during an INSERT operation.
 onInsertFinish ()
 Callback that is invoked after an INSERT operation.
 onUpdate ($what)
 Callback that is invoked during an UPDATE operation.
 onUpdateFinish ()
 Callback that is invoked after an UPDATE operation.

Detailed Description

A generic model object that is populated/committed to a database.

This class provides the object-relational mapping (ORM) for an object that will be read from/written to a database. Extend this object to inherit functions for finding/loading/saving your object to/from the database.

This class inherits from SModel2 all features needed to manage a set of attributes, but the functions in this class are specific to using a database for storage.

This is an abstract class that should be extended by model classes that map to actual database tables. When extending this class, you should immediately define static variables that define your database, table, and attributes:

Date:
Started 2/9/09

Updated 2/26/09

Author:
Joel Feiner <jfeiner@shodor.org>

Jonathan Stuart-Moore <jwsm@shodor.org>

Member Function Documentation

SDatabaseModel::commit ( $  updateObj = false  ) 

Save this object's attributes to a record in the database.

The database model commit function does the following:

  • Check if the object is valid
    • If the object isStored() (there is already a DB row for the object):
      • Use the object's $primaryKey attribute to find our row in $tableName
      • Begin a database transaction (if one is not in progress)
      • If the object is marked for deletion:
        • Delete the database row, but don't commit the transaction
        • Call onDelete(), which is a callback that derived classes can implement to perform additional processing during a DELETE operation
        • Commit the transaction and return true
      • Check for any attributes that are objects or foreign keys, and commit() those objects (this is done in the prepareUpdate() method)
      • Write an UPDATE query that only changes $currentValues (no need to modify $baseValues, as their values have not changed) in our DB row
      • Run the query on $DBI
    • If the object !isStored() (there's no record of it yet in the DB):
      • Check for any attributes that are objects, and commit() those objects (this is done in the prepareUpdate() method)
      • Write an INSERT query to save all values returned from getValues() (base values overridden by current values)
      • Run the query on $DBI
      • Set the $primaryKey attribute value to the mysql_insert_id
  • Pass on the list of attributes that need to have their 'commit' flag reset after an INSERT
    • Return true/false for success/failure
    Later, the DBI will call the finishUpdate(), finishInsert() or finishDelete() method, depending on the query, which will actually update the object and its attribute 'commit' flags, but only if the transaction succeeded. This way, if the transaction fails, we will not have objects lying around in an invalid state.

Returns:
[bool]: True on success; false on error

Reimplemented from SModel2.

Reimplemented in View_SDRResourceDetails, and View_SDRResourceMinimal.

SDatabaseModel::copy ( $  asNew = false  ) 

Attempts to make a copy of this object.

See SModel2::copy() for more. For database objects, this may be tricky because committing back to the DB may not be straightforward. The primary key is not copied if it is not an array since it may be auto-increment and thus should not be copied, but should be left alone.

Parameters:
$asNew [boolean]: if true, pretend this object was never in the DB
Returns:
[SDatabaseModel]: object that is copy of this object, or null on error

Reimplemented from SModel2.

SDatabaseModel::fromDB ( $  rep  ) 

Populate this object based on a link or representation stored in a foreign database field.

Parameters:
$rep [string]: The link/representation of the object
Override this function to populate this object from the value of $rep. By default, it will call populate and pass in $rep as the primary key. ???

SDatabaseModel::getConstraintForPrimaryKey ( $  skipStorageCheck = false  ) 

Get a constraints array that uniquely specifies this object by its primary key.

Parameters:
$skipStorageCheck [boolean]: do not use
Returns:
[array]: An array with one item, where the key is the object's primary key attribute, and the value is this object's value of the primary key. Return false if the object is not yet stored.

SDatabaseModel::getFormatted ( $  field,
$  format 
)

Retrieves a DATE/TIME field and formats it.

Parameters:
$field [string]: name of field to retrieve
$format [string]: strftime()-compatible string to format the field's value with
Returns:
[string]: formatted value of $field or false if field does not exist

SDatabaseModel::getPrimaryKey (  ) 

Retrieves primary key attribute name for this object.

Returns:
[string]: name of attribute that is considered the primary key, if any

SDatabaseModel::getTableName (  ) 

Retrieves name of table this object represents.

Returns:
[string]: name of table

SDatabaseModel::getXML ( $  options = array()  ) 

Overridden getXML() more specific for database classes.

All that this method does different is have the root node name default to the table name

Parameters:
$options [array]: array of options that control how XML is generated (see parent class)
Returns:
[mixed]: string of XML or SimpleXML object

Reimplemented from SModel2.

SDatabaseModel::isDatabaseAttribute ( $  attrName  ) 

Determines if given attribute is one that should go into the database.

See isDatabaseAttributeStatic().

Parameters:
$attrName [string]: name of attribute to check
Returns:
[boolean]: whether attribute satisfies conditions in isDatabaseAttributeStatic()

static SDatabaseModel::isDatabaseAttributeStatic ( $  info  )  [static]

Determines if a given attribute is one that should go into the database.

Attributes that go into the database are those which are not objects and are not marked as COMMIT_NOSOURCE and are not arrays.

Parameters:
$info [array]: attribute information (as would come from getAttributeInfo())
Returns:
[boolean]: whether attribute satisfies above conditions

SDatabaseModel::onDelete (  )  [protected]

Callback that is invoked during a DELETE operation.

This method is called after the row has been deleted successfully from the database, but before the transaction has completed. If it returns false, the transaction is cancelled. This method is to be used by derived classes to implement any special functionality that must take place when an object is being deleted, such as deleting, or preparing for deletion, external files. Note that this method is only called after the successful deletion of a row, not after the whole transaction succeeds. It is thus probably best to use onDeleteFinish() to do final cleanup activities as it is called after the transaction succeeds.

Returns:
[boolean]: true to continue transaction; false to cancel it

SDatabaseModel::onDeleteFinish (  )  [protected]

Callback that is invoked after a DELETE operation.

This method is called when a transaction that involves this object getting deleted is complete. The database is updated and committed, so this method cannot be used to cancel a pending DELETE. It should be used to clean up any external resources associated with this object.

SDatabaseModel::onInsert ( $  what  )  [protected]

Callback that is invoked during an INSERT operation.

This method is called after the INSERT query succeeds, but before the DB transaction is committed.

Parameters:
$what [array]: attributes and new values that will be inserted into the DB
Returns:
[boolean]: true to continue transaction; false to cancel it

SDatabaseModel::onInsertFinish (  )  [protected]

Callback that is invoked after an INSERT operation.

This method is called after the database transaction is complete and committed. The object is fully updated with new attributes and a primary key from mysql_insert_id, if needed.

SDatabaseModel::onUpdate ( $  what  )  [protected]

Callback that is invoked during an UPDATE operation.

This method is called after the UPDATE query succeeds, but before the DB transaction is committed.

Parameters:
$what [array]: attributes and new values that will be update in the DB
Returns:
[boolean]: true to continue transaction; false to cancel it

SDatabaseModel::onUpdateFinish (  )  [protected]

Callback that is invoked after an UPDATE operation.

This method is called after the database transaction is complete and committed. The object is fully updated and needs no further changes.

SDatabaseModel::populate ( $  constraints,
$  multi = false 
)

Populate this object's attributes from a record in the database.

The database model populate function will:

  • Call getListBase() or getListBaseMulti() to search the database using $constraints
  • Return false if no matches are found
  • Select the first matching database row
  • Copy values from the database row to the object's attributes
  • Report an error if there is a type mismatch
  • Otherwise, mark the object as stored and copy current attributes to base attributes, among other things
  • Return true/false based on success/failure of copying data

Parameters:
$constraints [array]: A set of search constraints to locate a database row
$multi [boolean]: if true, use getListBaseMulti() to grab a JOINed result set
Returns:
[bool]: True on success; false on error

SDatabaseModel::populateFromResults ( $  results  ) 

Populates this object from query results.

This allows you to populate this object using a custom query. All of the attributes relevant to this object must be named as they would be named in this object. That is, if this object has an attribute called 'foo', then the result attribute should also be called 'foo'. This is different from populateFromResultsMulti().

The results array must be two dimensional: a list of rows, each row being an associative array of attribute => value pairs. This is the same format as returned by DBI2::query()->toArray().

Parameters:
$results [array]: results array (described above)
Returns:
[boolean]: success or failure

SDatabaseModel::populateFromResultsMulti ( $  results,
$  mapping = null,
$  as = null 
)

Populates this object from query results.

This allows you to populate this object using a custom query. All of the attributes relevant to this object must be named 'TABLE_ATTRIBUTE' (e.g. 'MyTable_ATTR_id') This is different from populateFromResults().

The results array must be two dimensional: a list of rows, each row being an associative array of attribute => value pairs. This is the same format as returned by DBI2::query()->toArray().

Parameters:
$results [array]: results array (described above)
$mapping [array]: maps table and attribute aliases (comes from SQuery::getMapping())
$as [string]: alias of the table from which to populate this object
Returns:
[boolean]: success or failure

SDatabaseModel::setFormatted ( $  field,
$  newValue 
)

Updates a DATE/TIME field and formats according to what DB requires.

Parameters:
$field [string]: name of field to update
$newValue [string]: some type of time/date-indicating string that will be converged to standard DB format
Returns:
[boolean]: false if field does not exist, true otherwise

SDatabaseModel::toDB (  ) 

Provide a link to or representation of this object for storage in a foreign database field.

Override this function to return a value that will represent or link to this object. By default, it returns the object's primary key -- to be stored as a foreign key during a commit by another object.

Returns:
[string]: The link/representation of the object

The documentation for this class was generated from the following file:
Generated on Wed Nov 24 02:02:33 2010 for Common by  doxygen 1.5.6