Installation and setup.

Install the package

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

The migration creates three 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.

Morph maps are honoured. If Relation::enforceMorphMap() is active, the alias is what lands in 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. What the command does is advance the cascade to the next candidate and pick up queued work. See expiry and scheduling.

Notification channels

The package notifies the assignee at four moments. 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

Assignees that do not use Laravel's Notifiable trait are skipped without an error. See notifications.

Optional published assets

Two more tags exist, and neither is needed to run the package:

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. That is the constraint doing its job. 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.