Class:SmartestDataObject

From The Smartest Wiki
Jump to: navigation, search

SmartestDataObject is the primary class that provides the functionality for Smartest's Active record system. The class is always extended and only its subclasses are ever instantiated; there are never actual SmartestDataObject objects.

Subclasses of this class exist at three levels:

  • Base classes - these are auto-generated by Smartest and stored in System/Cache/ObjectModel/DataObjects/ and should never be edited. These classes provide the get/set methods and the built-in table-specific offsets. If learning Smartest for the first time, it is probably worth having a look at a few of them.
  • Basic object classes - used unless there is a specific reason to use one of the extended object classes below. Stored in System/Data/BasicObjects/
  • Extended object classes - Often used where one database table, such as Sets, is used for a number of different functionalities requiring different functionalities, such as SmartestCmsItemSet and SmartestAssetGroup. Stored in System/Data/ExtendedObjects/.

Offsets

The field names of the database, minus their prefixes, are also offsets that can be retrieved from the object at the template level. So if 'user_firstname' is the database field in the Users table and $user is our SmartestUser object (a SmartestDataObject subclass), then the first name field can be accessed in the template as:

<?sm:$user.firstname:?>

Thus, actual method calls are never needed (and strongly discouraged) in templates.

Standard offsets

In addition to actual data access, SmartestDataObject provides a number of standard offsets that are available to all its subclasses:

string $obj._class or $obj._php_class - returns the class name of the object.

string $obj._debug or $obj._print_r - prints out the object, including all its internal data. Only intended for debugging.

bool $obj.empty - if the object is a real object containing real data from the database, returns true, otherwise false. Works by detecting a value for the 'id' property.

Public methods

SmartestDataObject classes have standard get/set functions for actual database fields. These methods' names are generated from database column names, minus their prefix such as 'user_' or 'asset_', so that for example database field user_bio_asset_id becomes getBioAssetId() and setBioAssetId($id).

In addition to these methods, the SmartestDataObject class also has a number of standard methods that exist for all its subclasses and which help with basic CRUD operations.

Building objects from the database

object copy($class_name={class of current object}) Used for making additional data object instances that refer to the same database record, without querying the database a second time.

This is useful when you need to save just one field without committing any other changes to the database. You can also specify an alternative class to be used, which is useful when you need to copy the object as one of its subclasses instead (for instance you need SmartestRenderableAsset instead of SmartestAsset).

bool find($id) - called on a newly instantiated object with the ID of an existing table row, to look up that row and populate the object with data from it:

$u = new SmartestUser;
if($u->find(12)){
    // The user ID 12 exists, time to retrieve some data:
    $echo $u->getFirstName();
}

findBy($unique_field_name, $unique_field_identifier) - works similarly to find() but uses other unique fields (specified in $unique_field_name to look up the object:

$u = new SmartestUser;
if($u->findBy('username', 'marcus')){
    // The username 'marcus' exists, time to retrieve some data:
    $echo $u->getFirstName();
}

hydrate($raw_db_array) - The underlying SmartestMysql layer returns associative arrays of data where array keys are raw table column names, and values are raw database values. This method ingests one of these raw arrays and populates the data object with the values in the array.

$db = SmartestDatabase::getInstance('SMARTEST');
$result = $db->queryToArray("Some select query here");
$objects = array();

foreach($result as $raw_array){
    $a = new SmartestAsset; // SmartestAsset is a subclass of SmartestDataObject;
    $a->hydrate($raw_array); // hydrate brings the raw database data into the object and gets it ready for use.
    $objects[] = $a;
}

void refreshFromDatabase() - updates the object in cases where the data in the database may have changed since it was instantiated, but does not overwrite unsaved modifications.

Manipulate and retrieve data

void clearChanges() - resets and deletes any updates made with setXXX() methods that have not been committed with save(), but does not affect data in the database.

void delete() - removes the corresponding row from the database. This method is also often overridden by subclasses so that the delete cascades (foreign keys referring to the row are also deleted or amended, such as in many-to-many tables)

string getField($field_name) - retrieves data from one of the database column fields. Like the offsets above, the field names are referred to without the prefixes used in the actual database.

bool setField($field_name, $field_value) - sets data for the field (column) named in '$field_name. Like the offsets above, the field names are referred to without the prefixes used in the actual database.

NOTE: getField() and setField() are used internally by the other table-specific get/set methods, but it is preferable to use those methods rather that getField()/setField().

void save() - saves changes made to the item using the setXXX() methods or setField(). If the object is new, this will result in an <code>INSERT sql query being run, otherwise this will result in an UPDATE query.

string __toJson() - returns the object as a JSON-formatted string. Some SmartestDataObject subclasses will override this method in order to manipulate or filter the data. For instance, SmartestUser removes any sensitive data about passwords and authentication from the JSON representation returned by this function

Get information about the object

bool baseClassHasField($field_name) - allows you to double-check that the base class has the stated field.

string getClassName() - returns the class name of the SmartestDataObject object.

bool getCameFromDatabase() - lets you know whether this is an object that has been paired with a database row via find() or hydrate(), or whether it is new.

array getModifiedProperties() - returns an associative array of all properties that have been modified using setXXX() methods or setField(), but not yet saved to the database.