Documentation / Models

Models are classes defining a data structure, like the Models\Auth\User data structure used by the Core\Auth class.

These models are used to ease data-oriented development, mostly when using database-like data storage.

Models are using a lightweight ORM written specially for Orion. While this ORM isn’t comparable to other larger scale ORM engines like doctrine or propel, its simpleness and deep integration within the framework makes it a very useful feature and will most likely be sufficient for the everyday project. Moreover, Orion being highly extensible, you can integrate third-party ORMs manually for larger projects.

Base

A Model class base code is as follow :

// For a global model (located in /orion/models/)
namespace Orion\Models;
// Or for a local module model (located in /orion/modules/mymodule/models/) :
// namespace Orion\Modules\MyModule\Models;

use \Orion\Core;

class MyModel extends Core\Model
{

}

Please note that Models follow the standard namespaced naming convention used by Orion (see Naming convention).

Structure

Model classes can be divided into four parts : the object data structure, the object methods, the model definition and finally the model methods.

Object data structure

This part is composed of public attributes, defining the data object.

For example, a User model object’s data structure could be implemented as follow :

// [...]
class User extends Core\Model
{
    public $id;
    public $login;
    public $password;
    public $name;
    public $mail;
}

As you can see, a user would be defined by an id, a login, a password, a name and a mail address.

Object methods

This part is composed of public methods.

Object methods are mostly used to ease data transformation and formatting.

For example, you could define an object method to say hello to a user :

// [...]
class User extends Core\Model
{
   // [...]
   public function sayHello()
   {
       return 'Hello ' . $this->name . ' !';
   }
}

While this example may seem a little useless, you could definitely think of a better usage, like a method to generate an activation hash based on the user’s attributes.

Note that some public function names are reserved by the Core\Model class, like the save/delete/update trio (see Built-in object helpers).

Model definition

This part is composed of protected static attributes and a describe() method.

Indeed, while you have already defined your object’s data attributes, you still have to tell Orion which attribute does what. This is what we call model definition.

Going on with the User example, you could define its model like this :

// [...]
class User extends Core\Model
{
    // [...]
    protected static $table = 'orion_users';
    protected static $fields, $events, $primaryKeys;

    protected static function describe()
    {
       self::has( new Core\Model\Id( 'id', 'ID', true ) );
       self::has( new Core\Model\String( 'login', 'User login', 60, '[a-zA-Z0-9_\.]+', true ) );
       self::has( new Core\Model\Password( 'password', 'User password', true ) );
       self::has( new Core\Model\String( 'name', 'Full name', 255, null, true ) );
    }
}

Basically, what this code does is :

  • Tell Orion that this Model is bound to a database table named 'orion_users’.
  • Set up the required fields/events/primaryKeys static attributes.
  • Tell Orion the type of each of the object’s attributes and their properties.

Note that in this example, the fields/events/primaryKeys static attributes are only initialised and not assigned any value because we’re using the self::has() helper to describe each field. In short, what this helper does is fill automatically those three static attributes for you.

You could of course choose not to use the helper and defined each attribute manually inside the describe method (this method being more tedious, we will not go further into details).

Just remember that because of the way late static binding is implemented in PHP, the fields/events/primaryKeys static attributes MUST be initialized, whether you chose to use the helper or not.

Also, the different Core\Model\Field’s constructors are described in details in the Orion / Model fields section.

Model methods

These public static methods can be used to write model helpers or group complex queries inside a single function.

Let’s take the example of the User model. Now that you have defined pretty much everything describing the model, you can start writing some model helpers like this one :

// [...]
class User extends Core\Model
{
    // [...]
       public static function getLatestNames( $x=1 )
    {
       return self::get('name')
           ->limit( $x )
           ->order( 'id', Core\Query::DESCENDING )
           ->fetchAll();
    }
}

This method will return an array of the $x latest User objects, and each of these User objects will have your public object methods available. So you could easily write the following code inside a controller :

foreach( Models\User::getLatestNames( 10 ) as $user )
{
   echo $user->sayHello();
}

Built-in static helpers

get( [$field [,$fields...]] )

This helper starts a new select-like Core\Query and returns that Query object (see Orion / Query).

For example, if you want to fetch the names of all registered users, you can simply write :

$users = Models\User::get( 'name' )->fetchAll();
foreach( $users as $user ) echo $user->name . "
";

This method accepts different types of arguments :

  • No argument (All of the model’s fields will be selected).
  • An array of field names.
  • A variable-length argument list of field names.

query()

This helper returns a new Core\Query instance pre-configured to use the current model.

fetchPostData( [$object [, $mergeEmpty] )

This helper return $object or a new Model object instance filled with data matching its attributes, retrieved from $_POST. When using an $object already filled with some data, use $mergeEmpty to specify the overwriting behaviour of the method.

fetchRestData( [$object [, $mergeEmpty] )

This method has the same behaviour as the fetchPostData() method except that it uses the php://input stream to retrieve data (mostly used to fetch REST requests’ data).

Others

There are some static methods left that are less important and less used. If you want information about those, please refer to the API doc.

Built-in object helpers

These helpers are methods inherited by the Model objects (Models returned or instantiated during queries). Those are useful when handling instantiated Core\Models.

delete()

This method removes the object from the database/storage system. In short, it creates a new delete query using the object attributes as values for the model’s primary keys.

For example, considering you have written a getByName() model helper, you could use the following code to remove the user named 'John Doe’ from the database :

$user = Models\User::getByName( 'John Doe' );
$user->delete();

save()

This method follows the same behaviour as the delete() method, except for the fact that it actually saves the object into the database instead of removing it.

For example, the following code will add a new user into the database :

$user = new Models\User();
$user->name = 'Jane Doe';
$user->login = 'jane.doe';
$user->password = 'p4s5w0r7';

$user->encrypt()->save();

update()

This method follows the same behaviour as the delete() method, except for the fact that it actually updates the object into the database instead of removing it.

Like the delete() method, update() needs its object to have its primary attributes to be defined.

For example, the following code will prefix a user’s name with 'New ' :

$user = Models\User::get( 'id', 'name' )
   ->where('login', Core\Query::EQUAL, 'somelogin')
   ->fetch();

$user->name = 'New ' . $user->name;
$user->update();

As you can see, you have to get the 'id’ value of the user in order to complete the update query (considering 'id’ is the only primary key of the data model).

Please note the use of the Query object to fetch the user. You could definitely have written a model helper for this, but this example shows a way to use the Core\Query object returned by the get() model method.

© Orion, the PHP5 framework, 2011-2012 • Maintained by Thibaut Despoulain
Back to top