Models
Database models
Database models are objects specialized in working with database structures. They represent table rows in a database table and optionally define relationships within tables.
Database models are stored into the includes/models/database/ by default and are automatically loaded by the database connector in use upon startup (this behavior is defined only within the MySQL connector, which is the default database connector used by the platform. If you develop your own connector, you can use your own model loading logic.).
The platform also comes with an example model, named "Example", so you can see how you can programatically define a database table. When writing your own database models, keep the following suggestions in mind:
- Name the source file just like the table in the database, so you don't get confused.
- Suffix your model class name with _Record.
- The MySQL models loaded by the MySQL connector (the default connector provided) MUST extend the DB_Record class in order to be automatically loaded.
Model methods
NOTE that these methods are MySQL specific, and are directly related to the default connector provided by us (PDO-MySQL).
string Record->getTable()
Returns the table name this rows belongs to.
Registry Record->getFields()
Returns all the table fields. If a row has been loaded, the data will be available in the object returned by this method.
string Record->getTablePrefix()
Returns the row's table prefix if it was set, or an empty string otherwise.
string Record->getFieldsPrefix()
Returns the row's fields prefix, or an empty string if no prefix is used.
void Record->setUp()
This method defines the table meta data and the fields used. See the examples section for more information.
boolean Registry->find(int id)
This method is only available for rows that have a primary key that is auto incremented. If there's no row with the given id into the table, the internal data storage container is reset (all the data set on the object will be gone). If the row is found, the internal data storage container will be populated with the values of the row from the table.
boolean Registry->insert()
In order to run this method, you must populate the row fields first, excluding the id row (the non-null fields are mandatory). If the insert is successful, the id property of the row will be set to the id of the newly inserted row, the rest of the fields remaining intact. If the insert failed for what ever reason, an exception will be thrown (DatabaseConnectionException, DatabaseQueryException or DatabaseParameterBindingException).
void Registry->update()
Updates an existing row only if changes were made to the object. The Record class has an instance monitor to detect if any field has changed and if it did, it only updates the modified field.
void Registry->delete()
Deletes the current row from the database and clears the internal data storage container, if the row has an auto incremented primary key. Otherwise, an exception will be thrown.
array Registry->toArray()
Returns an array representation of the current row. The field names are prefixed with the field prefix.
The Record class also provides shortcuts (__get and __set method overrides for accessing the fields of the row it represents). Therefore, the following is possible:
echo $record->name; // will give you the value of the name field $record->name = 'Your name'; // will set the value of the name field
IMPORTANT NOTE: When accessing the field names using the notation above, do not specify the field prefix. The code above will work even if you have set your fields prefix to something like "pref_". If you do try to access the field with the prefix, the code will generate a Base_Exception exception.
Another interesting magical utility of the Record class is searching by a single field (feature available by overriding the __call method). Considering the snippet above, you can do the following:
$names = $record->findByName('John');
Observe the camelCased notation. The call above will return an array containing all the database rows whose name field value is "John" (a collection of stdClass objects). An important note here is that the search is exact. Here's the actual query that will be run against the database:
SELECT * FROM table WHERE name='John'