Skip to main content
The Model class provides an elegant ORM (Object-Relational Mapping) for interacting with your database. Each database table has a corresponding Model which is used to interact with that table.

​
Defining models

Create a model by extending the base Model class: 
use Aeros\Src\Classes\Model;

class User extends Model
{
    protected $table = 'users';
    protected $primary = 'id';
    protected $fillable = ['name', 'email', 'password'];
    protected $guarded = ['id', 'created_at'];
}

​
Properties

​
table
string
The database table associated with the model
​
primary
string
default:"id"
The primary key column name
​
fillable
array
default:"[]"
Columns that are mass assignable
​
guarded
array
default:"[]"
Columns that are protected from mass assignment

​
Retrieving models

​
find()

Find a single record or multiple records by filter criteria. 
// Find by ID
$user = User::find(1);

// Find by single condition
$user = User::find([['email', '=', '[email protected]']]);

// Find with multiple conditions
$users = User::find([
    ['status', '=', 'active'],
    ['role', '=', 'admin', 'OR'],
    ['role', '=', 'moderator']
]);

// Find with specific columns
$user = User::find(1, ['id', 'name', 'email']);
​
filter
int|array
required
ID or array of filter conditions
​
columns
array
default:"null"
Specific columns to retrieve (defaults to all)
​
return
Model|array|null
Returns Model instance, array of Models, or null if not found

​
Creating models

​
create()

Create a new record in the database. 
$user = User::create([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'password' => password_hash('secret', PASSWORD_DEFAULT)
]);
​
newValues
array
required
Associative array of column names and values
​
return
Model
Returns the newly created Model instance

​
createMany()

Insert multiple records at once. 
$users = User::createMany([
    ['name' => 'John', 'email' => '[email protected]'],
    ['name' => 'Jane', 'email' => '[email protected]'],
    ['name' => 'Bob', 'email' => '[email protected]']
]);
​
records
array
required
Array of associative arrays representing records
​
return
array
Returns array of created Model instances

​
Updating models

​
update()

Update one or more records. 
// Update specific records
User::update(
    ['status' => 'inactive'],
    [['last_login', '<', '2023-01-01']]
);

// Update instance
$user = User::find(1);
$user->name = 'Updated Name';
$user->update()->commit();
​
updatedValues
array
default:"[]"
Array of column values to update
​
where
array
default:"[]"
Filter conditions for which records to update
​
return
Model
Returns Model instance for method chaining

​
save()

Save changes to an existing model instance. 
$user = User::find(1);
$user->email = '[email protected]';
$user->save();
​
return
mixed
Returns result of the save operation

​
Deleting models

​
delete()

Delete one or more records. 
// Delete by condition
User::delete([['status', '=', 'banned']])->commit();

// Delete instance
$user = User::find(1);
$user->delete()->commit();
​
where
array
default:"[]"
Filter conditions for records to delete
​
return
Model
Returns Model instance for method chaining

​
Committing changes

​
commit()

Execute pending insert, update, or delete operations. 
$user = User::create(['name' => 'John']);
// Record is automatically committed

$user->update(['name' => 'Jane'])->commit();
User::delete([['id', '=', 5]])->commit();
​
return
mixed
Returns result of the database operation

​
Relationships

​
hasOne()

Define a one-to-one relationship. 
class User extends Model
{
    public function profile()
    {
        return $this->hasOne(Profile::class);
    }
}

// Usage
$profile = $user->profile()->first();
​
relatedModel
string
required
Related model class name
​
foreignKey
string
default:"null"
Foreign key on related table (auto-detected if null)
​
localKey
string
default:"null"
Local key on parent table (auto-detected if null)
​
return
HasOne
Returns HasOne relationship instance

​
hasMany()

Define a one-to-many relationship. 
class User extends Model
{
    public function posts()
    {
        return $this->hasMany(Post::class);
    }
}

// Usage
$posts = $user->posts()->get();
$activePosts = $user->posts()->where('status', 'published')->get();
​
relatedModel
string
required
Related model class name
​
foreignKey
string
default:"null"
Foreign key on related table (auto-detected if null)
​
localKey
string
default:"null"
Local key on parent table (auto-detected if null)
​
return
HasMany
Returns HasMany relationship instance

​
belongsTo()

Define an inverse relationship. 
class Post extends Model
{
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

// Usage
$user = $post->user()->first();
​
relatedModel
string
required
Related model class name
​
foreignKey
string
default:"null"
Foreign key on parent table (auto-detected if null)
​
ownerKey
string
default:"null"
Owner key on related table (auto-detected if null)
​
return
BelongsTo
Returns BelongsTo relationship instance

​
belongsToMany()

Define a many-to-many relationship using a pivot table. 
class User extends Model
{
    public function roles()
    {
        return $this->belongsToMany(Role::class);
    }
}

// Usage
$roles = $user->roles()->get();
$user->roles()->attach([1, 2, 3]);
$user->roles()->detach([2]);
$user->roles()->sync([1, 3, 4]);
​
relatedModel
string
required
Related model class name
​
pivotTable
string
default:"null"
Pivot table name (auto-detected if null)
​
foreignPivotKey
string
default:"null"
Foreign pivot key (auto-detected if null)
​
relatedPivotKey
string
default:"null"
Related pivot key (auto-detected if null)
​
localKey
string
default:"null"
Local key on parent table (auto-detected if null)
​
relatedKey
string
default:"null"
Related key on related table (auto-detected if null)
​
return
BelongsToMany
Returns BelongsToMany relationship instance

​
hasManyThrough()

Define a has-many-through relationship. 
class Country extends Model
{
    public function posts()
    {
        return $this->hasManyThrough(Post::class, User::class);
    }
}

// Usage
$posts = $country->posts()->get();
​
relatedModel
string
required
Final related model class name
​
throughModel
string
required
Intermediate model class name
​
firstKey
string
default:"null"
First foreign key (auto-detected if null)
​
secondKey
string
default:"null"
Second foreign key (auto-detected if null)
​
localKey
string
default:"null"
Local key on parent table (auto-detected if null)
​
secondLocalKey
string
default:"null"
Local key on intermediate table (auto-detected if null)
​
return
HasManyThrough
Returns HasManyThrough relationship instance

​
Utility methods

​
getPrimaryKey()

Get the primary key name for the model. 
$primaryKey = $user->getPrimaryKey(); // 'id'
​
return
string
Returns the primary key column name

​
getTableNameFromModel()

Get the database table name for the model. 
$tableName = $user->getTableNameFromModel(); // 'users'
​
return
string
Returns the table name

​
Examples

​
Complete model with relationships

class User extends Model
{
    protected $table = 'users';
    protected $primary = 'id';
    protected $fillable = ['name', 'email', 'password'];
    protected $guarded = ['id', 'created_at'];

    public function posts()
    {
        return $this->hasMany(Post::class);
    }

    public function profile()
    {
        return $this->hasOne(Profile::class);
    }

    public function roles()
    {
        return $this->belongsToMany(Role::class);
    }
}

​
Working with relationships

// Get user with posts
$user = User::find(1);
$posts = $user->posts()->get();

// Filter related records
$publishedPosts = $user->posts()
    ->where('status', 'published')
    ->get();

// Attach roles
$user->roles()->attach([1, 2, 3]);

// Sync roles (removes old, adds new)
$user->roles()->sync([2, 3, 4]);

Build docs developers (and LLMs) love

Get started for freeTalk to us