Download the PHP package andydefer/laravel-roster without Composer

Laravel Roster

Roster is a comprehensive Laravel package for advanced scheduling, availability, and booking management. Built with a robust architecture, it handles recurring availability, booked slots, and impediments with exhaustive business validation.

📦 Installation

Publish package resources:

Or manually:

🚀 Quick Start

1. Add the trait to your models

2. Create recurring availabilities

3. Schedule appointments

4. Manage temporary unavailability

5. Search for available slots

🛡️ Performance Protection: Absolute Minimum Duration

To prevent infinite loops and performance degradation, Roster enforces an absolute minimum duration of 10 minutes for ALL entity types (Availability, Schedule, Impediment).

Why 10 minutes?

When searching for available slots, the system generates time slots based on the duration. A duration that is too small would generate an enormous number of iterations:

Technical Protection Implementation

The protection is enforced at the lowest level of the validation system:

What happens if you try to configure less than 10 minutes?

Validation in Action

🔗 Polymorphic Scheduling Link System

Roster includes an advanced system that allows any Eloquent model to be associated with schedules with customizable metadata.

Attach resources to schedules

Manage attached resources

Direct usage from models

Eloquent relationships

Advanced use cases

1. Operating room management

2. Shared resource booking

3. Complex metadata for tracking

📋 Model Query Methods (HasRoster Trait)

The HasRoster trait includes methods to retrieve impediments and schedules of a model within a given period.

Added Methods

Simple Example

Practical Use Case

📖 Core Concepts

Immutability Principle

Roster prevents direct model mutations to ensure data integrity. All operations must go through appropriate services:

Single-action context

Each service is designed for a single action with its own context:

The 3 main entities

1. Availability: Defines when a resource is available (days, times, period)
2. Schedule: Represents a booked slot in an availability
3. Impediment: Temporarily blocks an availability

🛡️ Secure Architecture

Mutation access control

The system uses two contexts to control access:

Secure helpers

The availability_for(), schedule_for(), and impediment_for() helpers automatically create the necessary context:

🔍 Advanced Search and Data Consistency

first() method for targeted search

Automatic days consistency

The system automatically ensures consistency between specified days and validity periods:

Standardized days sorting

Utility functions always return days in standard week order (Monday → Sunday):

🎯 Exhaustive Business Validation

Roster includes 17 validation rules that guarantee system consistency:

Main rules:

• SchedulableValidationRule (110) - Checks for schedulable context presence
• RequiredFieldsRule (100) - Validates required fields per operation
• AvailabilityTemporalCoherenceRule (100) - Ensures temporal coherence
• TemporalConflictRule (80) - Prevents scheduling overlaps
• AvailabilityOverlapRule (80) - Prevents availability overlaps
• TimeRangeRule (85) - Validates time ranges (no multi-day spans)
• DurationRule (90) - Enforces minimum duration (with 10 minutes absolute minimum)

Rule visualization:

📊 Real-world Usage Examples

Medical clinic management

Room booking system

Recurrent impediment management

🔧 Complete API

Availability Service

Schedule Service

Impediment Service

⚙️ Configuration

Configuration file (config/roster.php)

Environment variables

🧪 Comprehensive Tests

The package includes 2300 tests covering all scenarios:

Tested scenarios:

• ✅ Full availability lifecycle
• ✅ Impediment management with conflicts
• ✅ Intelligent booking system
• ✅ Complex interactions (availabilities + impediments + schedules)
• ✅ Multi-user conflicts with shared resources
• ✅ Error handling and edge cases
• ✅ Performance testing with massive data
• ✅ Recovery after errors
• ✅ Realistic complex scenario (hospital with multiple specialists)
• ✅ Data consistency with automatic reconciliation
• ✅ first() method for targeted search
• ✅ Polymorphic link system with metadata
• ✅ Attached resource management (rooms, vehicles, equipment)
• ✅ Synchronization and detachment tests
• ✅ Minimum duration enforcement (10 minutes absolute minimum)
• ✅ Protection against infinite loops in slot generation

🚨 Error Handling

Duration validation error example

Reconciliation warning handling

📊 Development Tools

Validation rule debugging

Cache management

🤝 Contribution

1. Fork the repository
2. Create a branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Run tests

📄 License

This package is open-source and available under the MIT license.

🔗 Useful Links

• API Documentation
• Migration Guide
• Changelog
• Issues

Roster - A professional solution for advanced scheduling management, designed for critical applications where every minute counts. ⚕️⏰✨

With advanced search features, data consistency, exhaustive business validation, automatic protection against infinite loops (10 minutes absolute minimum duration), and a comprehensive polymorphic link system, Roster ensures the integrity of your scheduling systems in the most demanding environments.