ExpressionEngine® 3 User Guide

Legacy Documentation

You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.

Using the Model Service

Naming Conventions

Models follow the prefix naming conventions. Native models can be referred to either prefix-free or with the ee: prefix. All add-on models must be used with the add-on prefix.

Creating

To create a new instance of a model, simply pass its name to the make() method on the model service:

$template = ee('Model')->make('Template');

You can also pass an array of default model properties:

$template = ee('Model')->make('Template', array(
  'template_name' => 'test'
));

Setting and Getting Values

Models behave like regular objects. Their properties can be set and read directly:

$template->template_name = 'index';
var_dump($template->template_name); // 'index'

To bulk set data from an array, use the set() method:

$template->set(array(
  'template_name' => 'header',
  'template_notes' => 'This is the site header!'
));

Saving

To save a new or updated model, call save():

$template->template_notes = 'A great note!';
$template->save();

Deleting

To delete an existing model, call delete():

$template->delete();
echo $template->template_name;

Fetching

Full Documentation: Fetching Models

To fetch one or more existing models, use the get() method with a model name to specify which model to get, and then call all() to fetch a collection of all matching models:

$templates = ee('Model')->get('Template')->all();

You can also use first() to only grab the first one:

$template = ee('Model')->get('Template')->first();

Events

Full Documentation: Event Service

All models have basic support for the built-in event system. To listen to an event on a model, use the on method:

$my_model = ee('Model')->make('myaddon:MyModel');

$my_model->on('boom', function() use ($my_model)
{
  echo 'boom event happened on '.$my_model->getName();
});

To initiate an event, use the emit() method:

$my_model->emit('boom');

Any additional arguments passed to emit, will be passed on to the event handler.

Validation

After making changes to a model, you should call validate() to ensure it will save successfully. The result returned from validation is a result object from the Validation Service:

$template->template_name = 'Mike';
$result = $template->validate();

if ($result->isValid())
{
  $template->save();
}

Working with Relationships

Full Documentation: Working with Relationships

Models can be related to other models. All relationships can be accessed directly with their uppercase name:

$channel->ChannelEntries;

Depending on the type of relationship, this may return either a collection or a single other model. By convention, if the name is singular it returns a model otherwise it returns a collection.