README

Foundational Eloquent traits and scopes for strict, opinionated Laravel applications.

This package provides a set of reusable traits for common Eloquent patterns such as UUID keys, audit fields (creator/updater), media uploading, and multi-tenancy scoping.

Installation

composer require hatchyu/laravel-eloquent-foundation

Optionally, publish the configuration (if available in future updates):

php artisan vendor:publish --tag=eloquent-foundation-config

Usage

1. Primary Keys (UUID / ULID)

Easily switch your models to use UUIDs or ULIDs as primary keys.

UUID:

use Hatchyu\Eloquent\Foundation\Concerns\UuidPrimary;
use Illuminate\Database\Eloquent\Model;

class Project extends Model
{
    use UuidPrimary;
}

ULID:

use Hatchyu\Eloquent\Foundation\Concerns\UlidPrimary;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use UlidPrimary;
}

2. Audit Trails (Creator, Updater, Deleter)

Automatically track who created, updated, or deleted a record. These traits assume you have standard created_by, updated_by, and deleted_by columns in your database.

use Hatchyu\Eloquent\Foundation\Concerns\HasCreator;
use Hatchyu\Eloquent\Foundation\Concerns\HasUpdater;
use Hatchyu\Eloquent\Foundation\Concerns\HasDeleter;

class Post extends Model
{
    use HasCreator, HasUpdater, HasDeleter;
    
    // Automatically sets 'created_by' to Auth::id() on creation
    // Automatically sets 'updated_by' to Auth::id() on update
    // Automatically sets 'deleted_by' to Auth::id() on soft deletion
}

3. Media Uploading

The HasMediaUploader trait simplifies handling file uploads directly in your Eloquent models. It automatically detects UploadedFile instances assigned to attributes, uploads them to storage, and saves the path.

use Hatchyu\Eloquent\Foundation\Concerns\HasMediaUploader;

class User extends Model
{
    use HasMediaUploader;

    // Optional: Define upload path (defaults to 'uploads/default')
    const FILE_UPLOAD_PATH = 'uploads/avatars';
}

// Usage in Controller
$user->avatar = $request->file('avatar'); 
$user->save(); // File is uploaded, path is saved to DB

Features:

Automatic storage to public disk.
Deletes the old file when replaced.
Safe for usage within transactions (uploads effectively happen afterCommit).

4. Image URL Accessors

The HasImageUrls trait provides dynamic accessors for your image paths, useful for APIs.

use Hatchyu\Eloquent\Foundation\Concerns\HasImageUrls;

class User extends Model
{
    use HasImageUrls;

    protected array $imageFields = ['avatar'];
}

Result: If you have an avatar column, you automatically get:

$user->avatar_url (Original URL)
$user->avatar_thumb_url (Thumbnail URL)

You can customize the dimensions by overriding imageDimensions() in your model.

5. Multi-Tenancy (Branch Scoping)

The BelongsToBranchTenant trait provides robust multi-tenancy support for applications structured around "Branches".

use Hatchyu\Eloquent\Foundation\Concerns\BelongsToBranchTenant;

class Order extends Model
{
    use BelongsToBranchTenant;
}

Functionality:

Global Scope: Automatically filters queries to the current user's branch.
Auto-Assignment: Automatically assigns the current user's branch_id when creating models.
Security: Prevents users from creating or accessing records in branches they don't belong to.
Global Access: Supports "Global" records (where branch_id is NULL) if enabled via $allowsGlobalBranches.

Requirements: Your User model must implement the ProvidesBranchContext interface.

Helpers

The package includes global helper functions:

eloquent_ulid(): Generate a valid ULID string.
avatar_url($path, $width, $height): Generate a URL for an image path (supports resizing placeholders).

License

The MIT License (MIT). Please see License File for more information.

hatchyu / laravel-eloquent-foundation

Maintainers

Details