Models

Setup

Models in Core52 encapsulate data objects and all their related functionality, including loading from a database table, updating, and storing new objects.

Store Models in your app/models directory.

Naming

• Don’t use weird characters in your model names. Stick with letters, numbers, and underscores. Don’t start a model name with a number.
• Model file names are case sensitive (on UNIX) and must match the model class name.
• Use Capitalized_Snake_Case for model class names.
• Use singular nouns for model names.

Pattern

At a minimum, your model classes need to extend the base Model class, and to set the $_table and $_pk protected properties:

<?php

class User extends Model {

    # database table to load data from (required)
    protected $_table = 'users';

    # primary key column name (optional - default is 'id')
    protected $_pk = 'id';

    # optional database connection handle name
    protected $_database = 'default';

}

Manipulating Core52 Models

Creating

The Model::create() static method takes a class name and an associative array. This translates to an SQL INSERT query, and returns the resulting object:

# returns a User object
$obj = Model::create('User', array(
    'name' => 'Bob',
    'age'  => 25,
));

If you need to provide a custom SQL query for loading your model object data, put the query in your class definition and use _ID_ as the placeholder for the primary key value:

class User extends Model {
    protected $_table = 'users';
    protected $_pk = 'userId';
    protected custom_query = 'SELECT * FROM users WHERE type = "member" AND userId = _ID_';
}

Loading

To load a previously saved object, simply pass the ID of the database record you want to load to your model class constructor (this translates to an SQL SELECT query):

$obj = new User(3);

Note that Core52 caches the queries used to load models, so repeated loads of the same object will not cause excessive database queries to occur.

Alternately, if you have an array of data used in the Model, simply pass it to the constructor and it will skip the database query:

$user_data = array(
    'id' => 10,
    'name' => 'Bob',
    'age' => 29,
);
$obj = new User($user_data);

To test if the object loaded successfully, use the exists() method:

if($obj->exists()) {
    echo $obj->name.' is here!';
} else {
    echo 'User not found';
}

Updating

To update a model object, use the save() method. This will translate into either an SQL INSERT or an SQL UPDATE query, based on whether or not the primary key is present:

# returns TRUE or FALSE if the update succeeds or fails
$obj->save('name', 'Robert');  // field name, value

# you can also pass an associative array and save multiple fields at once:
$obj->save(array(
    'name' => 'Robert',
    'age'  => 27,
));

Note that the save() method automatically filters out fields that are not in the table schema associated with your model class.

Deleting

To delete a model object, use the delete() method. This will translate into an SQL DELETE and unsets the object variable:

$obj->delete();

Built-in Functionality

The Core52 Model base class provides several pieces of built-in functionality for your convenience. See the Model documentation for details. Here is a list of some of the functionality that is provided:

• Auto-loading sub-objects
• Deep-cloning model objects
• Bypass the query cache when reloading objects
• Stringification
• Introspection