Models

Overview

Eloquent models are organized by domain under app/Models/. Each domain directory contains the model file and optionally a Concerns/ subdirectory for traits.

---

Folder Structure

app/Models/
├── Academic/                # Academic domain
│   ├── AcademicYear.php
│   ├── SchoolClass.php
│   └── Concerns/
│       ├── HasRelations.php
│       └── HasScopes.php
├── Recruitment/             # Recruitment domain
│   ├── Vacancy/Vacancy.php
│   ├── Applicant/Applicant.php
│   └── ...
├── Platform/                # Shared/platform models
│   ├── User.php
│   ├── Asset/Asset.php
│   └── Setting/Setting.php
├── Institution/
├── Financial/
├── Geographic/
├── News/
├── Organization/
├── Support/
├── Assistant/
└── ContractManagement/

---

Conventions

Convention	Rule	Example
Namespace	App\Models\{Domain}\{Model}	App\Models\Recruitment\Candidate
Table name	Snake_case plural of model	candidates
Primary key	UUID (v4)	$table->uuid('id')->primary()
Timestamps	Always included	$table->timestamps()
Soft deletes	When applicable	use SoftDeletes

---

Common Traits

Traits shared across models live in app/Traits/Common/:

Trait	Purpose	Usage
HasLocalization	Resolve localized JSON columns	protected array $localizations = ['name']
HasContact	Attach contacts via master table	protected array $contacts = ['phone', 'email']
HasLog	Automatic activity logging	No config needed — just use HasLog
HasAsset	Dynamic asset relationships	protected array $assets = ['logo_asset_id']
HasUuids	Auto-generate UUID primary key	Inherited from base model

Trait Usage Example

namespace App\Models\School;

use App\Traits\Common\HasLocalization;
use App\Traits\Common\HasContact;
use App\Traits\Common\HasLog;
use Illuminate\Database\Eloquent\Model;

class School extends Model
{
    use HasLocalization, HasContact, HasLog;

    protected array $localizations = ['name', 'description'];
    protected array $contacts = ['phone', 'email', 'whatsapp'];
}

---

Concerns Pattern

For complex models, domain-specific logic is extracted into Concerns/ traits:

Model.php
Concerns/
├── HasAttributes.php    # Accessors, mutators, casts
├── HasRelations.php     # Relationship definitions
└── HasScopes.php        # Query scopes

---

Creating a New Model

php artisan make:model Models/Domain/ModelName --all

This generates the model, factory, seeder, migration, policy, and form request. Move the migration to the appropriate version directory afterward.

---

Key Files

File	Purpose
app/Models/{Domain}/*.php	Domain models
app/Traits/Common/	Shared traits (HasLocalization, HasContact, HasLog, HasAsset)
app/Models/Platform/User.php	User model (authentication, roles)