README

A production-ready PHP scheduling package for resource-constrained project scheduling (RCPSP). Designed for facilities with human resources and machines, particularly suited for manufacturing environments like dental labs.

Features

🎯 Resource-Constrained Scheduling - Handles employees, machines, and calendar constraints
📊 Precedence Management - Supports complex dependency graphs (DAG)
⏱️ Smart Duration Estimation - 5-level fallback chain with calibration support
📅 Flexible Calendars - Weekly patterns with date-specific overrides
👥 Experience Matching - Matches employee skills to case difficulty
🔄 Deterministic Algorithm - Same inputs always produce identical outputs
⚡ High Performance - O(n log n) greedy heuristic algorithm
✅ 100% Test Coverage - 95 comprehensive tests, all passing

Installation

composer require scheduler/scheduler

Requirements:

PHP 8.2 or higher
ext-json

Quick Start

use Scheduler\GreedyScheduler;

$scheduler = new GreedyScheduler();

$input = [
    'timezone' => 'UTC',
    'startAt' => '2025-01-06T09:00:00Z',
    'cases' => [
        [
            'caseId' => 'case-1',
            'dueBy' => '2025-01-06T17:00:00Z',
            'restorations' => [
                [
                    'restorationId' => 'rest-1',
                    'productionLineId' => 'line-1',
                    'steps' => [
                        [
                            'stepId' => 'a1111111-1111-4111-8111-111111111111',
                            'restorationId' => 'rest-1',
                            'requiresRoleId' => 'b2222222-2222-4222-8222-222222222222',
                            'estimatedDuration' => 'PT2H',
                            'predecessors' => [],
                        ],
                    ],
                ],
            ],
        ],
    ],
    'employees' => [
        [
            'employeeId' => 'emp-1',
            'roles' => [['roleId' => 'b2222222-2222-4222-8222-222222222222']],
            'weeklyCalendar' => [
                ['day' => 'Mo', 'segments' => [['start' => '09:00', 'end' => '17:00']]],
            ],
        ],
    ],
    'machines' => [],
    'productionLineRoleEstimations' => [],
];

$result = $scheduler->schedule($input);

// Access assignments
foreach ($result['assignments'] as $assignment) {
    echo "Step {$assignment['stepId']} assigned to {$assignment['employeeId']}\n";
    echo "Start: {$assignment['startAt']->format('c')}\n";
    echo "End: {$assignment['endAt']->format('c')}\n";
}

// Check for delays
if (!empty($result['delayReport']['delayedCases'])) {
    foreach ($result['delayReport']['delayedCases'] as $delayed) {
        echo "Case {$delayed['caseId']} is late by {$delayed['lateness']}\n";
    }
}

Documentation

Quick Start Guide - Get up and running in 5 minutes
API Reference - Complete API documentation
Architecture - System design and algorithms
Usage Examples - Real-world scenarios
Advanced Features - Advanced customization and optimization
Error Codes - Complete error reference
Test Strategy - Testing approach

Use Cases

Manufacturing Scheduling - Dental labs, machine shops, assembly lines
Project Planning - Multi-step workflows with resource constraints
Service Scheduling - Technician dispatch, maintenance planning
Production Planning - Job shop scheduling, batch processing

Key Concepts

Cases & Restorations

Case: Top-level container with client-facing deadline
Restoration: Belongs to a case, linked to production line version
Step: Schedulable unit that completes a restoration

Resources

Employees: Have roles and experience levels, work according to calendars
Machines: Have capabilities, can be required for specific steps
Calendars: Weekly patterns with date-specific overrides

Scheduling

Precedence Constraints: Steps can depend on other steps
Experience Matching: Employee experience must meet case difficulty
Duration Estimation: 5-level fallback chain with calibration
Delay Analysis: Automatic lateness detection and reporting

Testing

# Run all tests
./vendor/bin/phpunit

# Run specific test suite
./vendor/bin/phpunit tests/Unit/GreedySchedulerTest.php

# Run with coverage (requires xdebug)
./vendor/bin/phpunit --coverage-html coverage/

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

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

Credits

Developed using strict Test-Driven Development (TDD) methodology with 100% test coverage.

preneomit / scheduler

Maintainers

Details