Models

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 class, so everything CModel can do, BaseModel can do as well.