Roster Laravel Package

Getting Started

Start by installing the package via Composer:

composer require laravel/roster

Then publish the config and migration files:

php artisan vendor:publish --provider="Laravel\Roster\RosterServiceProvider"
php artisan migrate

The package introduces three core models: Roster, Position, and Assignment. Begin by defining a Roster (e.g., “On-Call Rotation”, “Frontend Team”) and Positions within it (e.g., “Senior Dev”, “Tech Lead”). Assign users (via Eloquent relationships) to positions via Assignments.

First use case:

$roster = Roster::create(['name' => 'Support Rotation']);
$position = Position::create(['name' => 'Night Shift', 'roster_id' => $roster->id]);
$assignment = Assignment::create([
    'position_id' => $position->id,
    'user_id' => 5,
    'starts_at' => now()->startOfWeek(),
    'ends_at' => now()->endOfWeek(),
]);

Check the config/roster.php file to customize behavior (e.g., date formatting, default slot duration).

Implementation Patterns

• Shared Rosters Across Teams: Use a single Roster model instance to represent shared scheduling contexts (e.g., “Global On-Call”), and scope assignments by roles or shifts. Attach custom attributes (e.g., shift_type, level) via the meta JSON column.

• Dynamic Roster Views: Leverage the built-in Blade components like @livewire('roster:calendar', ['rosterId' => 1]) (if Livewire optional) or compose your own table/list views using the Roster::with('positions.assignments.user') eager-loaded relationships.

• Permission Integration: Extend the Assignment model to add soft-deletable history, or observe Assignment events for syncing to external tools (e.g., Slack, Google Calendar). Use policies to restrict edit access on Roster/Position.

• Rolling Rotations: Automate recurring assignments with a job that runs weekly:

  Assignment::create([
      'position_id' => $nightShift->id,
      'user_id' => nextInRotation($users),
      'starts_at' => now()->addWeek(),
      'ends_at' => now()->addWeek()->endOfWeek(),
  ]);
  

• External Identity: Integrate with laravel/passport or laravel/sanctum by linking user_id to your auth provider’s principal. Avoid hard-coding users—favor relationships (Assignment::user()) over IDs.

Gotchas and Tips

• meta is nullable but not optional in logic: While assignments.meta defaults to {}, your business rules should always validate the presence of required keys (e.g., rotation_index, coverage_type) before trusting them.

• Date overloading: Avoid starts_at/ends_at ambiguity: always store in UTC and use Carbon’s ->shiftTimezone() in views—not directly in DB queries.

• Migrations assume users table exists: If you use a custom user model or guard, adjust the user_id column in the assignments migration accordingly.

• Extensibility trap: Don’t overwrite RosterServiceProvider registration to override model bindings—use Laravel’s bind() in AppServiceProvider instead:

  $this->app->bind(PositionInterface::class, CustomPosition::class);
  

• Debugging stale assignments: Run php artisan roster:report (custom Artisan command) to surface overlapping assignments, incomplete handovers, or assignments outside valid roster windows. The package doesn’t enforce logical constraints—you must validate them in your service layer.