[SUMMARY] DATA ACCESS OBJECT This is meant to be a simple, aggregate DAO, it will manage "parent/child" relationships with tables. it is meant as a simple scaffold to extend other more specific implementations. if you need something more complex it is expected that the object could be "decorated" with frther instances of itself to represent a "tree" structure
The DAO is modeled on two concepts "Entities", single row records from the DB; and "Collections", multiple Entities/rows whose foreign key is the primary key of the "foundation" entity/row. The "foundation" is the single entity record at the base of the instantiated object. the object provides some simple default "getters" & "setters". The "setter" methods ONLY update the object itself. The object tracks any changes to itself (only "current state", it does not track state changes) and will save its state on decomposition of the object. The objects state can optionally be saved to the database at any time
** conventions used in docs:
A correctly instantiated object will be populated by: (ON $config["database"] "SELECT * FROM $config["table"] WHERE $config["pk_field"] = $config["pk"] " )
[INSTANTIATION ERROR] The $OBJECT->$initialized member is the quickest way to verify that your object instantiated with a "valid record". if the object does not instatiate with a valid database record the value of $OBJECT->$initialized will remain FALSE If there is an error on instantiation the exception will be returned as the result here: $OBJECT->tables[$tableName]["values"]["EXCEPTION"]
["stub/NULL" INSTANTIATION] if the object is instantiated with NULL it will then create an emty "stub" object that can be "initialized" with the method:
$OBJECT->initialize($database, $tableName, $foundation=false) $database // the DSN (Data Source Name) i.e. "AUTH" $tableName // the table name i.e. globalUser
this will populate the $OBJECT->tables[$tableName]["values"] array by using the table definition returned by "SHOW COLUMNS FROM $tableName", (i.e. this object will ALWAYS return a full representation of the Entity record) any values defined as "NOT NULL" will be populated with the default value defined in the data base, any values allowing NULL will be populated with NULL.
!!! KNOW YOUR DATA MODEL!!! if the default value is a MySQL function it may be returned as a string (un tested)
The primary key of the new value will be "0", it will be updated to the value of mysql_insert_id() when the $OBJECT->save() method is called directly or by destruction of the object.
[AGGREGATING THE OBJECT] The oject can be easily "extended" by using the "join" methods:
A correctly "child member" will be populated by: (ON $database "SELECT * FROM $joinTable WHERE $fk_field = $fk/$OBJECT->root_pk " ) The syntax for accessing Entity/Collection "child members" differs see [DEFAULT GETTERS & SETTERS] below
[EXTENDTING AGGREGATION] initializeJoinRecord Besides being able to instatiate a "stub" object of the "foundation" Entity/row the object can also extent "stubs" of "child members". a stub of an Entity can be extended by: $OBJECT->initializeChildRecord($database, $tableName, $pk_field, $fk_field)
Like the "initialize" method on the "foundation" member it will create a defalt defintion based on the results of "SHOW COLUMNS FROM $tableName". The Entity is created using the same rules applied to the ["stub/NULL" INSTANTIATION]. The entity definition can then be modified using the "setter $OBJECT->set(table, field, value). on $OBJECT->save() the object will update the primary key references to the result returned by mysql_insert_id().
The object can also extend "stubs" of collection records with the method: $OBJECT->initializeCollectionRecord($database, $tableName, $pk_field, $fk_field)
The entity definition can then be modified using the "setter $OBJECT->set(table, field, value, pk). On $OBJECT->save() the object will update the primary key references of the Collection Entity/row.
[KEY PROPERTIES] $OBJECT->$initialized // set to bool TRUE when the object is initialized from a valid database record $OBJECT->root_pk // quick reference to the primary key of the "foundation" record $OBJECT->tables // an array of member values
[DEFAULT GETTERS & SETTERS] $OBJECT->get(table, field); //entity $OBJECT->set(table, field, value); //entity ALL Entity values can also be access through the public member: $OBJECT->tables[$tableName]["values"][$columnName]
$OBJECT->get(table, field, pk); // collection OBJECT->set(table, field, value, pk); //collection ALL Collection values can also be access through the public member: $OBJECT->tables[$tableName]["values"][$PK][$columnName]
[SAVING THE OBJECT STATE] The $OBJECT->save() method will save any changes to the object back to the database The $OBJECT->save() can be called on specific Entities/Collections by passing the table name $OBJECT->save($tableName)
| DAO | Class DAO |