zairakai/laravel-eloquent

Enhanced Eloquent model trait for automatic table management, primary key detection, and JSON serialization with column mapping

v2.5.2 2026-01-19 13:11 UTC

Requires

• php: ^8.3
• illuminate/database: ^11.0 || ^12.0
• illuminate/support: ^11.0 || ^12.0
• laravel/framework: ^11.0 || ^12.0

Requires (Dev)

• driftingly/rector-laravel: ^2.1
• ergebnis/composer-normalize: ^2.48
• friendsofphp/php-cs-fixer: ^3.64
• larastan/larastan: ^2.0 || ^3.0
• laravel/pint: ^1.26
• nunomaduro/phpinsights: ^2.13
• orchestra/testbench: ^8.0 || ^9.0
• phpmd/phpmd: ^2.15
• phpmetrics/phpmetrics: ^2.9
• phpstan/phpstan: ^1.10 || ^2.0
• phpunit/phpunit: ^10.0 || ^11.0
• rector/rector: ^2.3
• zairakai/laravel-dev-tools: ^2.7

MIT

• Stanislas Poisson

• serialization
• laravel
• models
• traits
• table
• eloquent
• zairakai

README

Enhanced Eloquent model classes and traits for automatic table management, primary key detection, JSON serialization with column mapping, and column resolution with migration support in Laravel applications.

Lightweight utility package Provides abstract classes (BaseModel, BasePivot) and trait (BaseTable) that eliminate boilerplate code when working with Eloquent models, especially for projects with custom database column naming conventions.

Installation

composer require zairakai/laravel-eloquent

Optional: Publish configuration and stubs:

php artisan vendor:publish --tag=laravel-eloquent          # Everything
php artisan vendor:publish --tag=laravel-eloquent-config   # Config only
php artisan vendor:publish --tag=laravel-eloquent-stubs    # Stubs only

Quick Start

Extend BaseModel (Recommended)

use Zairakai\LaravelEloquent\Models\BaseModel;

class User extends BaseModel
{
    public const COLUMNS = [
        'id'    => 'user_id',
        'email' => 'user_email',
        'name'  => 'full_name',
    ];

    protected $fillable = ['user_email', 'full_name'];
}

Use BaseTable Trait

use Illuminate\Database\Eloquent\Model;
use Zairakai\LaravelEloquent\Traits\BaseTable;

class User extends Model
{
    use BaseTable;

    public const COLUMNS = [
        'id'    => 'user_id',
        'email' => 'user_email',
    ];
}

For Pivot Tables

use Zairakai\LaravelEloquent\Models\BasePivot;

class RoleUser extends BasePivot
{
    public const TABLE_NAME = 'role_user';

    public const COLUMNS = [
        'roleId' => 'role_id',
        'userId' => 'user_id',
    ];
}

Custom Stubs

After publishing stubs, php artisan make:model uses BaseModel automatically:

php artisan vendor:publish --tag=laravel-eloquent-stubs
php artisan make:model Product

Stub	Description
model.stub	Standard model extending BaseModel
model.pivot.stub	Pivot model extending BasePivot
model.plain.stub	Model with BaseTable trait only

Model Conversion

Convert existing models to use BaseModel/BasePivot:

php artisan eloquent:convert --dry-run              # Preview changes
php artisan eloquent:convert                        # Convert app/Models
php artisan eloquent:convert --path=app/Models/Legacy
php artisan eloquent:convert --force                # No confirmation

API Reference

Methods

Method	Description
getTableName()	Get the resolved table name
getPrimaryKeyName()	Get the resolved primary key
resolveColumn($key)	Resolve application key to DB column
toReadableArray()	Convert to array with mapped keys
toJson()	JSON with mapped keys

Constants

Constant	Description
TABLE_NAME	Override automatic table name
PRIMARY_KEY	Override primary key
COLUMNS	Key → Column mapping
COLUMNS_DELETED	Deprecated key redirects (with logging)

Contributing

Getting Help