DEV Community: Mohamed Said

Notable: Polymorphic Notes for Any Laravel Model

Mohamed Said — Sun, 14 Sep 2025 06:04:17 +0000

Notable is a Laravel package that adds polymorphic note functionality to any Eloquent model.
Easily attach notes or comments to models with creator tracking, timestamps, and powerful query scopes.

This package is perfect for:

Internal comments
Audit logs
User feedback
Any kind of trackable textual annotations

✨ Key Features

🔗 Polymorphic Relationships – Attach notes to any Eloquent model.
👤 Creator Tracking – Track who created each note (creator is also polymorphic!).
⏰ Timestamps – Automatic created_at and updated_at tracking.
🔍 Query Scopes – Powerful query methods for filtering and searching notes.
⚙️ Configurable – Customize table names through the config file.
🚀 Easy Integration – Simple trait-based implementation.
📦 Laravel 10+ Ready – Built for modern Laravel applications.

🚀 Installation

Install via Composer:

composer require eg-mohamed/notable

Publish and run the migrations:

php artisan vendor:publish --tag="notable-migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag="notable-config"

🎯 Quick Start

1️⃣ Add the Trait to a Model

use MohamedSaid\Notable\Traits\HasNotables;

class SupportTicket extends Model
{
    use HasNotables;
}

2️⃣ Start Adding Notes

// Customer adds a note
$ticket->addNote('Still experiencing the issue', $customer);

// Support agent responds
$ticket->addNote('Investigating the problem', $agent);

// Get conversation history
$conversation = $ticket->getNotesWithCreator();

📚 Common Operations

// Retrieve notes
$ticket->getNotes();
$ticket->getNotesToday();
$ticket->getNotesThisWeek();
$ticket->getNotesThisMonth();
$ticket->getNotesInRange('2024-01-01', '2024-12-31');

// Search notes by content
$ticket->searchNotes('error');

// Check if a model has notes
if ($ticket->hasNotes()) {
    echo "This ticket has {$ticket->notesCount()} notes.";
}

🔍 Advanced Query Scopes

use MohamedSaid\Notable\Notable;

// Notes by specific creator
$notes = Notable::byCreator($user)->get();

// Notes without creator (system notes)
$systemNotes = Notable::withoutCreator()->get();

// Recent or older notes
$recentNotes = Notable::recent(7)->get();
$oldNotes = Notable::olderThan(30)->get();

// Date-based scopes
$todayNotes = Notable::today()->get();
$monthNotes = Notable::thisMonth()->get();
$rangeNotes = Notable::betweenDates('2024-01-01', '2024-12-31')->get();

// Search text
$searchResults = Notable::search('login')->get();

🗂 Database Schema

Column	Type	Description
`id`	bigint	Primary key
`note`	text	The note content
`notable_type`	varchar	Polymorphic type (model class)
`notable_id`	bigint	Polymorphic ID (model ID)
`creator_type`	varchar	Creator polymorphic type (nullable)
`creator_id`	bigint	Creator polymorphic ID (nullable)
`created_at`	timestamp	Created timestamp
`updated_at`	timestamp	Updated timestamp

You can customize the table name in config/notable.php:

return [
    'table_name' => 'notables',
];

💡 Example Use Cases

User Activity Log

$user->addNote('Password changed', $admin);
$user->addNote('Logged in', $user);

Order Tracking

$order->addNote('Order shipped', $system);
$order->addNote('Delivered successfully', $staff);

Support Tickets

$ticket->addNote('User reported an error', $customer);
$ticket->addNote('Fix deployed', $developer);

👨‍💻 Contributing & Support

Issues & bug reports: GitHub Issues
Pull requests are welcome!
Licensed under the MIT License.

Referenceable: Generate Unique Laravel Model References the

Mohamed Said — Sun, 14 Sep 2025 05:59:57 +0000

In many web applications, generating unique reference numbers for models is a common requirement.
Whether you're building:

an e-commerce platform that needs order numbers,
an invoicing system requiring invoice references, or
any application that needs trackable identifiers,

managing reference number generation can quickly become complex.

Referenceable is a Laravel package by Mohamed Said that simplifies this challenge.
It enables the generation of customizable model reference numbers with flexible formats and powerful configuration options.

✨ Main Features

Multiple Generation Strategies
Random, sequential, and template-based reference generation.
Highly Configurable
Define prefixes, suffixes, separators, and more.
Template System
Use placeholders like {YEAR}, {MONTH}, {SEQ}, {RANDOM} for complex formats.
Sequential Numbering
Auto-incrementing sequences with reset options (daily, monthly, yearly).
Validation & Verification
Built-in reference validation and uniqueness checking.
Collision Handling
Automatic collision detection and resolution.
Multi-Tenancy Support
Tenant-aware reference generation.
Artisan Commands
Comprehensive CLI tools for management and maintenance.
Performance Optimized
Caching, batch processing, and database transactions.

🚀 Example Usage

1️⃣ Migration

Create a migration with a reference_number column:

Schema::create('status_letters', function (Blueprint $table) {
    $table->id();
    $table->string('reference_number')->unique()->index();
    // other columns...
    $table->timestamps();
});

2️⃣ Model Configuration

Use the HasReference trait and configure the reference strategy:

use MohamedSaid\Referenceable\Traits\HasReference;

class StatusLetter extends Model
{
    use HasReference;

    protected $referenceColumn = 'reference_number';
    protected $referenceStrategy = 'template';
    protected $referenceTemplate = [
        'format' => '{PREFIX}-{YEAR}{MONTH}{SEQ}',
        'sequence_length' => 4,
    ];
    protected $referencePrefix = 'STL';
    // Generates: STL-2025090001, STL-2025090002...
}

🔀 Other Strategies

Random Strategy:

protected $referenceStrategy = 'random';
protected $referencePrefix = 'STL';
protected $referenceLength = 6;
protected $referenceCase = 'upper';
// Generates: STL-A12BC3

Sequential Strategy:

protected $referenceStrategy = 'sequential';
protected $referencePrefix = 'STL';
protected $referenceSequential = [
    'start' => 1000,
    'min_digits' => 4,
    'reset_frequency' => 'monthly', // never, daily, monthly, yearly
];
// Generates: STL-001000, STL-001001, STL-001002...

✅ Tip: You can also configure references globally in config/referenceable.php instead of per model.

🛠 Useful Methods & Scopes

// Manually generate without saving
$reference = $statusLetter->generateReference();

// Check if a model has a reference
if ($statusLetter->hasReference()) {
    echo "Reference Number: " . $statusLetter->reference;
}

// Find a record by reference number
$statusLetter = StatusLetter::findByReference('STL-2025090001');

// Query references starting with a prefix
$lettersThisMonth = StatusLetter::referenceStartsWith('STL-202509')->get();

⚡ Installation

Install via Composer and run the install command:

composer require eg-mohamed/referenceable
php artisan referenceable:install

View the source code on GitHub: github.com/EG-Mohamed/Referenceable