Notable Laravel Package: Add Notes to Any Eloquent Model

GitHub Repository: https://github.com/EG-Mohamed/Notable

Introduction

Notable is a simple and powerful Laravel package that allows you to attach notes to any Eloquent model using polymorphic relationships.

It is useful for applications that need internal comments, admin notes, activity logs, support ticket updates, audit notes, customer feedback, or any type of text annotation connected to a model.

Instead of building a custom notes system for every model, Notable gives you a reusable trait-based solution that works with users, orders, invoices, tickets, products, bookings, and more.

Why Use Notable?

Many Laravel applications need a way to store extra information about records. For example, an admin may need to leave a note on a customer account, a support agent may need to add updates to a ticket, or a staff member may need to track changes on an order.

Notable solves this by giving you a clean and flexible way to attach notes to any model without duplicating database tables or logic.

Key Features

• Attach notes to any Eloquent model
• Polymorphic relationships for flexible model support
• Optional creator tracking for each note
• Creator tracking also supports polymorphic models
• Automatic created_at and updated_at timestamps
• Simple trait-based integration
• Useful query scopes for filtering notes
• Search notes by text content
• Retrieve notes by date, creator, or time range
• Configurable table name
• Built for modern Laravel applications
• Ideal for admin panels, CRMs, support systems, and internal tools

Installation

Install the package using Composer:

composer require eg-mohamed/notable

Publish and run the migrations:

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

Optionally, publish the configuration file:

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

Quick Start

1. Add the Trait to Your Model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use MohamedSaid\Notable\Traits\HasNotables;

class User extends Model
{
    use HasNotables;
}

2. Add Notes to the Model

$user = User::find(1);

// Add a simple note
$user->addNote('User completed onboarding process');

// Add a note with creator
$admin = User::find(2);
$user->addNote('Account verified by admin', $admin);

3. Retrieve Notes

$notes = $user->getNotes();

4. Check If a Model Has Notes

if ($user->hasNotes()) {
    echo "This user has {$user->notesCount()} notes";
}

Complete Usage Guide

Adding Notes

You can add a basic note to any model that uses the HasNotables trait.

$model->addNote('Something noteworthy happened');

You can also attach a creator to the note.

$model->addNote('Action performed by current user', $currentUser);
$model->addNote('System generated note', $systemBot);

The creator can be any Eloquent model, not only a user model. This makes the package flexible for admins, staff members, bots, system accounts, or any custom creator model.

Retrieving Notes

Get all notes for a model:

$notes = $model->getNotes();

Get notes with creator information:

$notesWithCreators = $model->getNotesWithCreator();

Get the latest note:

$latestNote = $model->getLatestNote();

Get notes created by a specific creator:

$adminNotes = $model->getNotesByCreator($admin);

Check whether the model has notes:

$hasNotes = $model->hasNotes();

Count notes:

$count = $model->notesCount();

Date-Based Note Retrieval

Notable includes helper methods for retrieving notes by date.

$todayNotes = $model->getNotesToday();

$weekNotes = $model->getNotesThisWeek();

$monthNotes = $model->getNotesThisMonth();

$rangeNotes = $model->getNotesInRange('2026-01-01', '2026-12-31');

Searching Notes

Search notes by text content:

$searchResults = $model->searchNotes('error');

This is useful for support systems, admin dashboards, audit trails, and internal logs where teams need to find specific notes quickly.

Managing Notes

Update a Note

$model->updateNote($noteId, 'Updated note content');

Delete a Note

$model->deleteNote($noteId);

Query Scopes

The package includes useful query scopes through the Notable model.

use MohamedSaid\Notable\Notable;

Get Notes by Creator

$notes = Notable::byCreator($user)->get();

Get System Notes Without Creator

$systemNotes = Notable::withoutCreator()->get();

Get Recent Notes

Get notes from the last 7 days:

$recentNotes = Notable::recent()->get();

Get notes from the last 30 days:

$lastMonth = Notable::recent(30)->get();

Get Older Notes

$oldNotes = Notable::olderThan(30)->get();

Date-Based Scopes

$todayNotes = Notable::today()->get();

$weekNotes = Notable::thisWeek()->get();

$monthNotes = Notable::thisMonth()->get();

$yearNotes = Notable::thisYear()->get();

Filter Notes Between Dates

$rangeNotes = Notable::betweenDates('2026-01-01', '2026-12-31')->get();

Search Note Content

$searchResults = Notable::search('error')->get();

$containingText = Notable::containingText('login')->get();

Combine Multiple Scopes

$recentAdminNotes = Notable::byCreator($admin)
    ->thisMonth()
    ->search('important')
    ->orderBy('created_at', 'desc')
    ->get();

Database Schema

The package creates a notables table.

| Column | Type | Description | |---|---|---| | id | bigint | Primary key | | note | text | The note content | | notable_type | varchar | Polymorphic model class | | notable_id | bigint | Polymorphic model ID | | creator_type | varchar | Creator polymorphic model class, nullable | | creator_id | bigint | Creator polymorphic model ID, nullable | | created_at | timestamp | Date and time when the note was created | | updated_at | timestamp | Date and time when the note was updated |

Configuration

Publish the configuration file:

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

The configuration file is located at:

config/notable.php

Example configuration:

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

You can change the table name if your application needs a different database structure.

Advanced Examples

User Activity Log

Notable can be used to build a simple activity log for users.

use Illuminate\Database\Eloquent\Model;
use MohamedSaid\Notable\Traits\HasNotables;

class User extends Model
{
    use HasNotables;

    public function logActivity(string $activity, ?Model $performer = null)
    {
        return $this->addNote("User activity: {$activity}", $performer);
    }
}

Usage:

$user->logActivity('Logged in', $user);

$user->logActivity('Password changed', $user);

$user->logActivity('Account suspended', $admin);

Order Tracking

You can use Notable to track order updates and status changes.

use MohamedSaid\Notable\Traits\HasNotables;

class Order extends Model
{
    use HasNotables;

    public function addStatusNote(string $status, ?User $updatedBy = null)
    {
        return $this->addNote("Order status changed to: {$status}", $updatedBy);
    }
}

Usage:

$order->addStatusNote('Processing', $staff);

$order->addStatusNote('Shipped', $system);

$order->addStatusNote('Delivered');

Support Tickets

Notable is also useful for support ticket conversations and internal ticket updates.

use MohamedSaid\Notable\Traits\HasNotables;

class SupportTicket extends Model
{
    use HasNotables;
}

Usage:

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

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

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

Admin Panel Notes

You can use Notable inside admin panels to allow staff members to leave private notes on records.

$customer->addNote('Customer requested a callback tomorrow.', auth()->user());

$order->addNote('Payment manually verified by finance team.', auth()->user());

$product->addNote('Supplier price changed this month.', auth()->user());

This makes it useful for Laravel admin panels built with tools such as Filament, Laravel Nova, or custom dashboards.

Model Relationships

You can access notes directly through Eloquent relationships.

$model->notables();

This returns a MorphMany relationship.

Eager Loading Notes

Load notes and their creators with the parent model:

$users = User::with('notables.creator')->get();

Load notes after retrieving the model:

$user->load('notables');

Note Model Properties

Each note record gives you access to the note content, parent model, creator, and timestamps.

$note = $model->getLatestNote();

$note->note;

$note->notable;

$note->creator;

$note->created_at;

$note->updated_at;

Common Use Cases

Notable is suitable for:

• Customer notes
• Admin comments
• Internal staff notes
• Support ticket updates
• Order tracking notes
• User activity logs
• Audit notes
• CRM notes
• Product notes
• Booking notes
• Invoice notes
• System-generated notes
• Moderation notes
• Team collaboration comments

Example Note Scenarios

User completed onboarding process.

Account verified by admin.

Order status changed to: Processing.

Customer requested a refund.

Support agent is investigating the issue.

Payment was manually approved.

Product price was updated.

Booking was rescheduled by staff.

System generated a warning for failed login attempts.

Best Practices

Use Clear Note Text

Write notes that are easy to understand later.

Good example:

Customer requested to change the delivery date to June 10, 2026.

Less useful example:

Changed.

Track the Creator When Possible

Passing the creator helps your team understand who added each note.

$model->addNote('Customer account verified.', auth()->user());

Use Notes for Human-Readable Context

Notable is best for text-based context, internal communication, and record history. For strict system auditing, you may still want to use a dedicated audit log package alongside Notable.

Eager Load Notes When Needed

When displaying many models with notes, use eager loading to avoid unnecessary database queries.

$orders = Order::with('notables.creator')->get();

Contributing

Contributions are welcome. You can submit issues, feature requests, or pull requests through the GitHub repository.

Bug Reports

If you discover a bug, please open an issue on GitHub:

https://github.com/EG-Mohamed/Notable/issues

License

This package is open-source software licensed under the MIT License.

Credits

Created and maintained by Mohamed Said.

GitHub:

https://github.com/EG-Mohamed

Conclusion

Notable gives Laravel developers a clean and reusable way to add notes to any Eloquent model.

It supports polymorphic relationships, creator tracking, timestamps, query scopes, date filters, search, and simple note management. This makes it a practical choice for Laravel applications that need internal comments, customer notes, support updates, audit notes, or activity-related annotations.

For source code and installation details, visit the GitHub repository:

https://github.com/EG-Mohamed/Notable