Models

Defining and including

Previous: Installing - Next: Validations

Define your models where you want like

    <?php
        class User extends TORM\Model {};
        User::setOrder("name");
    ?>

Include them and use like

    <?php
        // this will search for user with id 1
        $user = User::find(1);

        // this will create a new user
        $user = new User();
        $user->name  = "John Doe";
        $user->email = "[email protected]";
        $user->level = 1
        $user->save();
    ?>

Models methods

• setTableName(name) - The default behaviour is use the name of the current class with a 's' on the end (there is an Inflection class for pluralization). Change to the table name you want.
• setOrder(order) - Default sort order.
• setPK(pk) - Primary key column. Defaults to id.
• setIgnoreCase(boolean) - Process all columns as lower case. Defaults to true.
• updateAttributes(array) - Update the attributes on a model and save it: $user->updateAttributes(array("email"=>"[email protected]","level"=>3))

Pluralization

The pluralization rules must be set before any model definition. It is done by the TORM\Inflection class, where we can define rules to SINGULAR,PLURAL and IRREGULAR, like:

    TORM\Inflections::push(TORM\Inflections::IRREGULAR,"person","people");
    TORM\Inflections::push(TORM\Inflections::SINGULAR ,'/ao$/i',"oes"); // portuguese, 'acao' becomes 'acoes'
    TORM\Inflections::push(TORM\Inflections::PLURAL   ,'/oes$/i',"ao"); // portuguese, 'acoes' becomes 'acao'

Any other convertion is made appending an "s" to the end for plural and removing the "s" on the end for singular.

Primary keys values

Primary keys values can be set using some behaviours of the Driver:

• PRIMARY_KEY_DELETE - This will remove the primary key column from the INSERT clause, sending a NULL value. To make this works, your primary key column must be an auto-increment column. This works right now for MySQL and SQLite.

• PRIMARY_KEY_SEQUENCE - This will ask for the next value from a SEQUENCE. The sequence name will be the table model name appended with _sequence, for example, users_sequence. If the sequence does not exists, it will be created. This works right now for Oracle.

• Implementing a getNewPKValue method on the model - If there is a getNewPKValue method on the model, it will be called to get the value of a new primary key. The method must be static.

Callbacks

We can use some callbacks with save and destroy. The before ones, if returning false, will invalidate the associated action, and the after ones will just be called after the action is executed.

1. beforeSave(function) (before INSERT and UPDATE) - Eval the function return and if it's true, the current object will be saved.
2. afterSave(function) - Called after the object is saved.
3. beforeDestroy(function) - Eval the function return and if it's true, the current object will be destroyed.
4. afterDestroy(function) - Called after the object is destroyed.
5. afterInitialize() - Called after the object is initialized.

Example:

class User extends TORM\Model {
   public function before_save() {
      return true; // dummy return, should be a valid test
   }
   public function after_save() {
      return true; // dummy return, should be a valid test
   }
   public function before_destroy() {
      return true; // dummy return, should be a valid test
   }
   public function after_destroy() {
      return true; // dummy return, should be a valid test
   }

   public function afterInitialize() {
      $this->name = strtoupper($this->name);
   }
}
User::beforeSave("before_save");
User::afterSave("after_save");
User::beforeDestroy("before_destroy");
User::afterDestroy("after_destroy");

Dirty objects

We can track changes on the object attributes using some methods as the described below:

$user = User.find(1);
echo $user->name; // "Old Name"

$user->name = "New Name";
echo $user->name_changed; // true
echo $user->name_was; // "Old Name"
var_dump($user->name_change); // array("Old Name","New Name")
var_dump($user->changed()); // array("name")
var_dump($user->changes()); // array("name"=>array("Old Name","New Name"))

We have some "attributes" with prefixes like <attr>_:

• changed - Returns true if the attribute changed
• was - Returns the old value
• change - Returns an array with the old and current values

And the following methods:

• changed() - Returns the changed attributes names as an array
• changes() - Returns an indexed array with the attribute names as keys and the old and current values as the values

The current values becomes the old values when the object is saved, so:

$user = User.find(1);
echo $user->name; // "Old Name"

$user->name = "New Name";
echo $user->name_changed; // true
$user->save();

$user->name = "Another name";
echo $user->name_changed; // true
var_dump($user->name_change); // array("New Name","Another Name")

Previous: Installing - Next: Validations