Installation and setup.

Install the package

composer require byrcsc/laravel-assignment
php artisan vendor:publish --tag="assignment-migrations"
php artisan migrate

The migration creates these tables:

Publish the config first when you need it

Publish the configuration before running the migration when your models do not use integer keys, or when you want different table names. The migration reads both from config, so changing them afterwards means altering tables by hand.

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

Set the key type for either side of an assignment when its models use uuid, ulid, or string keys:

ASSIGNMENT_ASSIGNABLE_KEY_TYPE=uuid
ASSIGNMENT_ASSIGNEE_KEY_TYPE=ulid

Both default to id, which is an unsigned big integer. The setting is one value per side rather than one per model, so every assignable shares a key type and every assignee shares another. See configuration.

Add the traits

use ByRcsc\LaravelAssignment\Concerns\Assignable;
use ByRcsc\LaravelAssignment\Concerns\Assignee;

class Enquiry extends Model
{
    use Assignable;
}

class Tradie extends Model
{
    use Assignee;
}

Neither trait adds columns to your tables. Both read and write the assignments table through polymorphic columns, so a model can be assignable, an assignee, or both.

The package honours morph maps. If Relation::enforceMorphMap() is active, the package writes the alias to assignable_type and assignee_type.

Schedule the tick

One command expires overdue offers, advances their cascades, and flushes the queue:

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('assignment:tick')->everyMinute();

The schedule is optional for correctness. An overdue offer stops holding its slot the moment its expires_at passes, whether or not the command has run. The command advances the cascade to the next candidate and picks up queued work. See expiry and scheduling.

Notification channels

The package notifies the assignee when their work changes. Mail is the only channel on by default, because it is the only one that needs nothing installed:

// config/assignment.php
'notification_channels' => ['mail'],

Adding 'database' requires Laravel's notifications table:

php artisan make:notifications-table
php artisan migrate

The package skips assignees that do not use Laravel's Notifiable trait, and raises no error. See notifications.

Optional published assets

The package runs without these tags:

php artisan vendor:publish --tag="assignment-translations"
php artisan vendor:publish --tag="assignment-views"

Publish them to change the notification wording or the mail markup. See notifications.

Verify the installation

$enquiry = Enquiry::query()->create([]);
$tradie = Tradie::query()->create([]);

$enquiry->assign($tradie);

$enquiry->assignee()->is($tradie);   // true
$enquiry->assignments()->count();    // 1

If assign() throws SlotOccupied, the slot already holds an open row. The unique index raises that exception by design. See exceptions.

What to read next

• Quick start to route an enquiry through a policy rather than naming the assignee.
• Configuration for every key and its default.
• Assignments and slots for what "open" means.