Download the PHP package azaharizaman/nexus-scheduler without Composer

Nexus\Scheduler

A framework-agnostic job scheduling engine that manages future-dated instructions through contracts, delegating execution to domain packages and persistence to the application layer.

Overview

The Nexus\Scheduler package serves as the central repository for future-dated instructions. It manages when an action should happen, but delegates what the action is (domain logic) and how the action is executed (job runner/queue).

Core Principles

1. Complete Decoupling: Stateless design with all persistence via ScheduleRepositoryInterface
2. Execution Agnostic: Unaware of runtime environment (Laravel Queue, pure Cron, etc.)
3. Handler-Based: Domain packages implement JobHandlerInterface for their specific job types
4. Time Control: Testable via ClockInterface injection
5. Hybrid Retry: Handlers signal intent, engine manages execution

Architecture

The Scheduling Paradigm

Execution Flow

1. Scheduling Phase (Domain → Scheduler)

   • Domain package calls $scheduler->schedule(ScheduleDefinition)
   • ScheduleManager creates ScheduledJob value object
   • Persists via ScheduleRepositoryInterface

2. Execution Phase (Cron → Queue → Handler)

   • External cron job calls ProcessScheduledJobs command
   • Command retrieves due jobs via $manager->getDueJobs()
   • For each job, dispatches to queue via JobQueueInterface
   • Queue worker invokes appropriate JobHandlerInterface::handle()
   • Handler returns JobResult with retry intent
   • ExecutionEngine updates status and re-queues if needed
3. Retry Strategy (Hybrid Delegation)
   • Handler decides: "Should retry? Custom delay?"
   • Engine executes: Status update, queue dispatch, exponential backoff
   • Clean separation: Domain logic (intent) vs. Infrastructure (mechanism)

Installation

1. Install Package

2. Optional: Install Cron Expression Support

3. Implement Required Contracts in Your Application

4. Bind Interfaces in Service Provider

Usage

1. Schedule a Job

2. Implement a Job Handler

3. Register Handler (Tagged Service)

4. Process Scheduled Jobs (Cron)

Add to your cron:

Handler Registration Pattern

The package uses tagged services for handler discovery, avoiding tight coupling to concrete domain classes.

Domain Package Responsibility

1. Implement JobHandlerInterface
2. Tag in service provider: $app->tag([YourHandler::class], 'scheduler.handlers')

Scheduler Package Responsibility

1. Receive iterable $handlers via constructor injection
2. Build internal JobType => HandlerInterface mapping
3. Dispatch to appropriate handler based on job type

Zero coupling: The scheduler never knows concrete handler class names.

Retry Strategy

Hybrid Delegation Model

Handler (Domain Logic): Decides retry intent

ExecutionEngine (Infrastructure): Manages retry mechanism

• Updates job status (FAILED → PENDING)
• Increments retry_count
• Dispatches to queue with specified delay
• Applies exponential backoff if no custom delay
• Marks as FAILED_PERMANENT if shouldRetry === false

Decision Flowchart

Value Objects

ScheduledJob

Immutable representation of a scheduled job with business logic methods:

ScheduleRecurrence

Defines repetition rules:

JobResult

Handler's response with retry intent:

Enums

JobType

Extensible enum for domain-specific job types:

JobStatus

Lifecycle state with transition validation:

Testing

Time Control

Use ClockInterface for deterministic testing:

Running the Package Test Suite

The Scheduler package now ships with a dedicated PHPUnit 11 smoke suite plus deterministic in-memory adapters under tests/Support/. Run it locally before contributing new functionality:

What the suite covers today:

• ScheduleManagerTest validates successful dispatch, permanent-failure handling, and recurring job rollover.
• Support doubles (MutableClock, InMemoryScheduleRepository, TrackingJobQueue, CallbackJobHandler) keep tests framework-agnostic.

Future work will extend coverage across value objects, the recurrence engine, and execution engine edge cases. Contributions should include corresponding tests that reuse the provided adapters or add new deterministic doubles inside tests/Support/.

Future Features (v2)

Calendar Export

The CalendarExporterInterface is defined but bound to NullCalendarExporter (throws FeatureNotImplementedException) in v1.

Planned v2 features:

• Generate iCal files for scheduled jobs
• Google Calendar URL generation
• Outlook integration

📖 Documentation

Package Documentation

• Getting Started Guide
• API Reference
• Integration Guide
• Basic Usage Example
• Advanced Usage Example

Additional Resources

• IMPLEMENTATION_SUMMARY.md - Implementation progress
• REQUIREMENTS.md - Requirements
• TEST_SUITE_SUMMARY.md - Tests
• VALUATION_MATRIX.md - Valuation

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions, please refer to the main Nexus ERP repository.