$table

Specifies the database table that this model primarily works with. This only applies to the built-in CRUD methods. You are not restricted to using only this table in your own queries.

$primaryKey

This is the name of the column that uniquely identifies the records in this table. This does not necessarily have to match the primary key that is specified in the database, but is used with methods like find() to know what column to match the specified value to.

$useAutoIncrement

Specifies if the table uses an auto-increment feature for $primaryKey. If set to false then you are responsible for providing primary key value for every record in the table. This feature may be handy when we want to implement 1:1 relation or use UUIDs for our model. The default value is true.

$returnType

The Model’s find*() methods will take a step of work away from you and automatically return the resulting data, instead of the Result object.

This setting allows you to define the type of data that is returned. Valid values are ‘array’ (the default), ‘object’, or the fully qualified name of a class that can be used with the Result object’s getCustomResultObject() method.

Using the special ::class constant of the class will allow most IDEs to auto-complete the name and allow functions like refactoring to better understand your code.

$useSoftDeletes

If true, then any delete() method calls will set deleted_at in the database, instead of actually deleting the row. This can preserve data when it might be referenced elsewhere, or can maintain a “recycle bin” of objects that can be restored, or even simply preserve it as part of a security trail. If true, the find*() methods will only return non-deleted rows, unless the withDeleted() method is called prior to calling the find*() method.

This requires either a DATETIME or INTEGER field in the database as per the model’s $dateFormat setting. The default field name is deleted_at however this name can be configured to any name of your choice by using $deletedField property.

$allowedFields

This array should be updated with the field names that can be set during save(), insert(), or update() methods. Any field names other than these will be discarded. This helps to protect against just taking input from a form and throwing it all at the model, resulting in potential mass assignment vulnerabilities.

$allowEmptyInserts

Added in version 4.3.0.

Whether to allow inserting empty data. The default value is false, meaning that if you try to insert empty data, DataException with “There is no data to insert.” will raise.

You may also change this setting with the allowEmptyInserts() method.

$updateOnlyChanged

Added in version 4.5.0.

Whether to update Entity’s only changed fields. The default value is true, meaning that only changed field data is used when updating to the database. So if you try to update an Entity without changes, DataException with “There is no data to update.” will raise.

Setting this property to false will ensure that all allowed fields of an Entity are submitted to the database and updated at any time.

$casts

Added in version 4.5.0.

This allows you to convert data retrieved from a database into the appropriate PHP type. This option should be an array where the key is the name of the field, and the value is the data type. See Model Field Casting for details.

Dates

Validation

Callbacks

csv

Casting as csv uses PHP’s internal implode() and explode() functions and assumes all values are string-safe and free of commas. For more complex data casts try array or json.

datetime

You can pass a parameter like datetime[ms] for date/time with milliseconds, or datetime[us] for date/time with microseconds.

The datetime format is set in the dateFormat array of the database configuration in the app/Config/Database.php file.

$model = model('SomeModel');

$now = \CodeIgniter\I18n\Time::now();

// The following code passes the microseconds to Query Builder.
$model->where('my_dt_field', $now->format('Y-m-d H:i:s.u'))->findAll();
// Generates: SELECT * FROM `my_table` WHERE `my_dt_field` = '2024-07-28 18:57:58.900326'

// But the following code loses the microseconds.
$model->where('my_dt_field', $now)->findAll();
// Generates: SELECT * FROM `my_table` WHERE `my_dt_field` = '2024-07-28 18:57:58'

timestamp

The timezone of the Time instance created will be the default timezone (app’s timezone), not UTC.

enum

Added in version 4.7.0.

You can cast fields to PHP enums. You must specify the enum class name as a parameter, like enum[App\Enums\StatusEnum].

Enum casting supports:

• Backed enums (string or int) - The backing value is stored in the database

• Unit enums - The case name is stored in the database as a string

Creating Custom Handlers

At first you need to create a handler class for your type. Let’s say the class will be located in the app/Models/Cast directory:

<?php

namespace App\Models\Cast;

use CodeIgniter\DataCaster\Cast\BaseCast;
use InvalidArgumentException;

// The class must inherit the CodeIgniter\DataCaster\Cast\BaseCast class
class CastBase64 extends BaseCast
{
    public static function get(
        mixed $value,
        array $params = [],
        ?object $helper = null,
    ): string {
        if (! is_string($value)) {
            self::invalidTypeValueError($value);
        }

        $decoded = base64_decode($value, true);

        if ($decoded === false) {
            throw new InvalidArgumentException('Cannot decode: ' . $value);
        }

        return $decoded;
    }

    public static function set(
        mixed $value,
        array $params = [],
        ?object $helper = null,
    ): string {
        if (! is_string($value)) {
            self::invalidTypeValueError($value);
        }

        return base64_encode($value);
    }
}

If you don’t need to change values when getting or setting a value. Then just don’t implement the appropriate method:

<?php

namespace App\Models\Cast;

use CodeIgniter\DataCaster\Cast\BaseCast;
use InvalidArgumentException;

class CastBase64 extends BaseCast
{
    public static function get(
        mixed $value,
        array $params = [],
        ?object $helper = null,
    ): string {
        if (! is_string($value)) {
            self::invalidTypeValueError($value);
        }

        $decoded = base64_decode($value, true);

        if ($decoded === false) {
            throw new InvalidArgumentException('Cannot decode: ' . $value);
        }

        return $decoded;
    }
}

Registering Custom Handlers

Now you need to register it:

<?php

namespace App\Models;

use App\Models\Cast\CastBase64;
use CodeIgniter\Model;

class MyModel extends Model
{
    // ...

    // Specify the type for the field
    protected array $casts = [
        'column1' => 'base64',
    ];

    // Bind the type to the handler
    protected array $castHandlers = [
        'base64' => CastBase64::class,
    ];

    // ...
}

Parameters

In some cases, one type is not enough. In this situation, you can use additional parameters. Additional parameters are indicated in square brackets and listed with a comma like type[param1, param2].

<?php

namespace App\Models;

use App\Models\Cast\SomeHandler;
use CodeIgniter\Model;

class MyModel extends Model
{
    // ...

    // Define a type with parameters
    protected array $casts = [
        'column1' => 'class[App\SomeClass, param2, param3]',
    ];

    // Bind the type to the handler
    protected array $castHandlers = [
        'class' => SomeHandler::class,
    ];

    // ...
}

<?php

namespace App\Models\Cast;

use CodeIgniter\DataCaster\Cast\BaseCast;

class SomeHandler extends BaseCast
{
    public static function get(
        mixed $value,
        array $params = [],
        ?object $helper = null,
    ): mixed {
        var_dump($params);
        /*
         * Output:
         * array(3) {
         *   [0]=>
         *   string(13) "App\SomeClass"
         *   [1]=>
         *   string(6) "param2"
         *   [2]=>
         *   string(6) "param3"
         * }
         */
    }
}

find()

Returns a single row where the primary key matches the value passed in as the first parameter:

<?php

$user = $userModel->find($userId);

The value is returned in the format specified in $returnType.

You can specify more than one row to return by passing an array of primaryKey values instead of just one:

<?php

$users = $userModel->find([1, 2, 3]);

findColumn()

Returns null or an indexed array of column values:

<?php

$user = $userModel->findColumn($columnName);

$columnName should be a name of single column else you will get the DataException.

findAll()

Returns all results:

<?php

$users = $userModel->findAll();

This query may be modified by interjecting Query Builder commands as needed prior to calling this method:

<?php

$users = $userModel->where('active', 1)->findAll();

You can pass in a limit and offset values as the first and second parameters, respectively:

<?php

$users = $userModel->findAll($limit, $offset);

first()

Returns the first row in the result set. This is best used in combination with the query builder.

<?php

$user = $userModel->where('deleted', 0)->first();

withDeleted()

If $useSoftDeletes is true, then the find*() methods will not return any rows where deleted_at IS NOT NULL. To temporarily override this, you can use the withDeleted() method prior to calling the find*() method.

<?php

// Only gets non-deleted rows (deleted = 0)
$activeUsers = $userModel->findAll();

// Gets all rows
$allUsers = $userModel->withDeleted()->findAll();

onlyDeleted()

Whereas withDeleted() will return both deleted and not-deleted rows, this method modifies the next find*() methods to return only soft deleted rows:

<?php

$deletedUsers = $userModel->onlyDeleted()->findAll();

insert()

The first parameter is an associative array of data to create a new row of data in the database. If an object is passed instead of an array, it will attempt to convert it to an array.

The array’s keys must match the name of the columns in the $table, while the array’s values are the values to save for that key.

The optional second parameter is of type boolean, and if it is set to false, the method will return a boolean value, which indicates the success or failure of the query.

You can retrieve the last inserted row’s primary key using the getInsertID() method.

<?php

$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

// Inserts data and returns inserted row's primary key
$userModel->insert($data);

// Inserts data and returns true on success and false on failure
$userModel->insert($data, false);

// Returns inserted row's primary key
$userModel->getInsertID();

allowEmptyInserts()

Added in version 4.3.0.

You can use allowEmptyInserts() method to insert empty data. The Model throws an exception when you try to insert empty data by default. But if you call this method, the check will no longer be performed.

<?php

$userModel->allowEmptyInserts()->insert([]);

You may also change this setting with the $allowEmptyInserts property.

You can enable the check again by calling allowEmptyInserts(false).

update()

Updates an existing record in the database. The first parameter is the $primaryKey of the record to update. An associative array of data is passed into this method as the second parameter. The array’s keys must match the name of the columns in a $table, while the array’s values are the values to save for that key:

<?php

$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

$userModel->update($id, $data);

Multiple records may be updated with a single call by passing an array of primary keys as the first parameter:

<?php

$data = [
    'active' => 1,
];

$userModel->update([1, 2, 3], $data);

When you need a more flexible solution, you can leave the parameters empty and it functions like the Query Builder’s update command, with the added benefit of validation, events, etc:

<?php

$userModel
    ->whereIn('id', [1, 2, 3])
    ->set(['active' => 1])
    ->update();

save()

This is a wrapper around the insert() and update() methods that handle inserting or updating the record automatically, based on whether it finds an array key matching the primary key value:

<?php

// Defined as a model property
$primaryKey = 'id';

// Does an insert()
$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

$userModel->save($data);

// Performs an update, since the primary key, 'id', is found.
$data = [
    'id'       => 3,
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];
$userModel->save($data);

The save method also can make working with custom class result objects much simpler by recognizing a non-simple object and grabbing its public and protected values into an array, which is then passed to the appropriate insert or update method. This allows you to work with Entity classes in a very clean way. Entity classes are simple classes that represent a single instance of an object type, like a user, a blog post, a job, etc. This class is responsible for maintaining the business logic surrounding the object itself, like formatting elements in a certain way, etc. They shouldn’t have any idea about how they are saved to the database. At their simplest, they might look like this:

<?php

namespace App\Entities;

class Job
{
    protected $id;
    protected $name;
    protected $description;

    public function __get($key)
    {
        if (property_exists($this, $key)) {
            return $this->{$key};
        }
    }

    public function __set($key, $value)
    {
        if (property_exists($this, $key)) {
            $this->{$key} = $value;
        }
    }
}

A very simple model to work with this might look like:

<?php

namespace App\Models;

use CodeIgniter\Model;

class JobModel extends Model
{
    protected $table         = 'jobs';
    protected $returnType    = \App\Entities\Job::class;
    protected $allowedFields = [
        'name', 'description',
    ];
}

This model works with data from the jobs table, and returns all results as an instance of App\Entities\Job. When you need to persist that record to the database, you will need to either write custom methods, or use the model’s save() method to inspect the class, grab any public and private properties, and save them to the database:

<?php

// Retrieve a Job instance
$job = $model->find(15);

// Make some changes
$job->name = 'Foobar';

// Save the changes
$model->save($job);

Saving Dates

Added in version 4.5.0.

When saving data, if you pass Time instances, they are converted to strings with the format defined in dateFormat['datetime'] and dateFormat['date'] in the database configuration.

Primary Key Validation

Added in version 4.7.0.

The insert(), insertBatch() (when $useAutoIncrement is false), update(), and delete() methods validate primary key values before executing database queries. Invalid values such as null, 0, '0', empty strings, booleans, empty arrays, or nested arrays will throw an InvalidArgumentException with a specific error message.

If you need to customize this behavior (e.g., to allow 0 as a valid primary key for legacy systems), you can override the validateID() method in your model.

delete()

Takes a primary key value as the first parameter and deletes the matching record from the model’s table:

<?php

$userModel->delete(12);

If the model’s $useSoftDeletes value is true, this will update the row to set deleted_at to the current date and time. You can force a permanent delete by setting the second parameter as true.

An array of primary keys can be passed in as the first parameter to delete multiple records at once:

<?php

$userModel->delete([1, 2, 3]);

If no parameters are passed in, will act like the Query Builder’s delete method, requiring a where call previously:

<?php

$userModel->where('id', 12)->delete();

purgeDeleted()

Cleans out the database table by permanently removing all rows that have ‘deleted_at IS NOT NULL’.

<?php

$userModel->purgeDeleted();

Validating Data

The Model class provides a way to automatically have all data validated prior to saving to the database with the insert(), update(), or save() methods.

Setting Validation Rules

The first step is to fill out the $validationRules class property with the fields and rules that should be applied.

If you have custom error message that you want to use, place them in the $validationMessages array:

<?php

namespace App\Models;

use CodeIgniter\Model;

class UserModel extends Model
{
    // ...

    protected $validationRules = [
        'username'     => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
        'email'        => 'required|max_length[254]|valid_email|is_unique[users.email]',
        'password'     => 'required|max_length[255]|min_length[8]',
        'pass_confirm' => 'required_with[password]|max_length[255]|matches[password]',
    ];
    protected $validationMessages = [
        'email' => [
            'is_unique' => 'Sorry. That email has already been taken. Please choose another.',
        ],
    ];
}

If you’d rather organize your rules and error messages within the Validation Config File, you can do that and simply set $validationRules to the name of the validation rule group you created:

<?php

namespace App\Models;

use CodeIgniter\Model;

class UserModel extends Model
{
    // ...

    protected $validationRules = 'users';
}

The other way to set the validation rules to fields by functions,

class CodeIgniter\Model

CodeIgniter\Model::setValidationRule($field, $fieldRules)

Parameters:

• $field (string)

• $fieldRules (array)

This function will set the field validation rules.

Usage example:

<?php

$fieldName  = 'username';
$fieldRules = 'required|max_length[30]|alpha_numeric_space|min_length[3]';

$model->setValidationRule($fieldName, $fieldRules);

CodeIgniter\Model::setValidationRules($validationRules)

Parameters:

• $validationRules (array)

This function will set the validation rules.

Usage example:

<?php

$validationRules = [
    'username' => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
    'email'    => [
        'rules'  => 'required|max_length[254]|valid_email|is_unique[users.email]',
        'errors' => [
            'required' => 'We really need your email.',
        ],
    ],
];
$model->setValidationRules($validationRules);

The other way to set the validation message to fields by functions,

CodeIgniter\Model::setValidationMessage($field, $fieldMessages)

Parameters:

• $field (string)

• $fieldMessages (array)

This function will set the field wise error messages.

Usage example:

<?php

$fieldName              = 'name';
$fieldValidationMessage = [
    'required' => 'Your name is required here',
];
$model->setValidationMessage($fieldName, $fieldValidationMessage);

CodeIgniter\Model::setValidationMessages($validationMessages)

Parameters:

• $validationMessages (array)

This function will set the field messages.

Usage example:

<?php

$fieldValidationMessage = [
    'name' => [
        'required'   => 'Your baby name is missing.',
        'min_length' => 'Too short, man!',
    ],
];
$model->setValidationMessages($fieldValidationMessage);

Getting Validation Result

Now, whenever you call the insert(), update(), or save() methods, the data will be validated. If it fails, the model will return boolean false.

Getting Validation Errors

You can use the errors() method to retrieve the validation errors:

<?php

if ($model->save($data) === false) {
    return view('updateUser', ['errors' => $model->errors()]);
}

This returns an array with the field names and their associated errors that can be used to either show all of the errors at the top of the form, or to display them individually:

<?php if (! empty($errors)): ?>
    <div class="alert alert-danger">
    <?php foreach ($errors as $field => $error): ?>
        <p><?= esc($error) ?></p>
    <?php endforeach ?>
    </div>
<?php endif ?>

Retrieving Validation Rules

You can retrieve a model’s validation rules by accessing its validationRules property:

<?php

$rules = $model->validationRules;

You can also retrieve just a subset of those rules by calling the accessor method directly, with options:

<?php

$rules = $model->getValidationRules($options);

The $options parameter is an associative array with one element, whose key is either 'except' or 'only', and which has as its value an array of fieldnames of interest:

<?php

// get the rules for all but the "username" field
$rules = $model->getValidationRules(['except' => ['username']]);
// get the rules for only the "city" and "state" fields
$rules = $model->getValidationRules(['only' => ['city', 'state']]);

Validation Placeholders

The model provides a simple method to replace parts of your rules based on data that’s being passed into it. This sounds fairly obscure but can be especially handy with the is_unique validation rule. Placeholders are simply the name of the field (or array key) that was passed in as $data surrounded by curly brackets. It will be replaced by the value of the matched incoming field. An example should clarify this:

<?php

namespace App\Models;

use CodeIgniter\Model;

class MyModel extends Model
{
    // ...

    protected $validationRules = [
        'id'    => 'max_length[19]|is_natural_no_zero',
        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,{id}]',
    ];
}

In this set of rules, it states that the email address should be unique in the database, except for the row that has an id matching the placeholder’s value. Assuming that the form POST data had the following:

<?php

$_POST = [
    'id'    => 4,
    'email' => 'foo@example.com',
];

then the {id} placeholder would be replaced with the number 4, giving this revised rule:

<?php

namespace App\Models;

use CodeIgniter\Model;

class MyModel extends Model
{
    // ...

    protected $validationRules = [
        'id'    => 'max_length[19]|is_natural_no_zero',
        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,4]',
    ];
}

So it will ignore the row in the database that has id=4 when it verifies the email is unique.

This can also be used to create more dynamic rules at runtime, as long as you take care that any dynamic keys passed in don’t conflict with your form data.

asArray()

Returns data from the next find*() method as associative arrays:

<?php

$users = $userModel->asArray()->where('status', 'active')->findAll();

asObject()

Returns data from the next find*() method as standard objects or custom class instances:

<?php

// Return as standard objects
$users = $userModel->asObject()->where('status', 'active')->findAll();

// Return as custom class instances
$users = $userModel->asObject('User')->where('status', 'active')->findAll();