Models

This document is for a version of Craft CMS that is no longer supported. Please refer to the latest version →

Models are containers for data. Just about every time information is passed between services, controllers, and templates in Craft, it’s passed via a model.

To create a model, first create a new models/ subfolder within your plugin’s folder. Then create a new file in that folder, named with this format:

[PluginHandle]_[ModelName]Model.php

If your plugin name is “Cocktail Recipes”, and your model name is Ingredient, the file would be named CocktailRecipes_IngredientModel.php.

Create a new class in that file, with the same name as the filename:

<?php
namespace Craft;

class CocktailRecipes_IngredientModel extends BaseModel
{
    protected function defineAttributes()
    {
        return array(
            'name' => AttributeType::String,
            'type' => array(AttributeType::Enum, 'values' => "alcohol,mixer,other"),
        );
    }
}

That’s it! You will now be able to create new instances of the model, and run validation on them.

# Instantiating your Model

You can create new instances of your model just like any other PHP class:

<?php
namespace Craft;

$ingredient = new CocktailRecipes_IngredientModel();
$ingredient->name = "Tonic Water";
$ingredient->type = "mixer";

In the event that you already have an array of key-value pairs that maps to a model’s attributes, you can use the populateModel() static method instead, provided by BaseModel:

<?php
namespace Craft;

$ingredient = CocktailRecipes_IngredientModel::populateModel($data);

There’s also a corresponding populateModels() static method if you have an array of arrays of key-value pairs:

<?php
namespace Craft;

$ingredients = CocktailRecipes_IngredientModel::populateModels($data);

These functions also accept instances of BaseModel and BaseRecord rather than arrays.

# Validation

After filling up your model instance with values, validating it is quite simple:

<?php
namespace Craft;

if ($ingredient->validate())
{
    // It validates!
}
else
{
    // Here's a list of all the errors, grouped by attribute:
    $ingredient->getErrors();

    // Here's a list of errors for a single attribute:
    $ingredient->getErrors('name');
}

# Further Reading

BaseModel is an instance of Yii’s CModel (opens new window) class, so everything CModel can do, BaseModel can do as well.