ExpressionEngine Docs

# Model Service

- Naming Conventions
- Creating
- Setting and Getting Values
- Saving
- Deleting
- Fetching
- Events
- Validation
- Working with Relationships

ExpressionEngine has a complex set of data types, such as Channels, Members, Templates, and Categories. These have properties and constraints, as well as relationships and complex storage requirements. The model service helps smooth out interacting with ExpressionEngine’s data types by providing an API that mimics their natural language description as closely as is feasible. You do not query for `channel_data` joined on `channel_titles`; instead, you simply get a channel entry with its fields.

## 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.