# peppeocchi/php-cron-scheduler architecture

> Architecture diagram of the GitHub repository peppeocchi/php-cron-scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peppeocchi/php-cron-scheduler
- Repository: https://github.com/peppeocchi/php-cron-scheduler

## Overview

##### Main Components
- Scheduler Core: At the heart is the Scheduler class (located in src/GO/Scheduler.php). This component is responsible for managing, triggering, and executing the scheduled jobs.
- Job Representation: The Job class (src/GO/Job.php) encapsulates information about a scheduled task. It is likely used to keep the job definition, schedule, and status.
- Failure Handling: The FailedJob class (src/GO/FailedJob.php) captures details and exceptions in case job execution fails.
- Traits for Extended Functionality: The project uses traits (found in src/GO/Traits/, e.g. Interval.php and Mailer.php) to add specialized scheduling features like configuring intervals and email notification behavior.
- Testing Suite: The tests directory indicates comprehensive test coverage (unit tests for job scheduling, interval calculations, and mailer logic) ensuring the reliability of the components.
- External Dependencies: Notice the optional integration with SwiftMailer for sending emails and the use of the Cron Expression library (referenced in the README). Also, there are composer configuration files and CI/CD configurations (e.g., .github/workflows, .coveralls.yml) which support continuous integration, testing, and coverage reporting.

##### Relationships and Interactions
- Each Job object can be configured with additional behaviors by incorporating traits (Interval, Mailer) – represent these as extensions or “mixins” connected to Job.
- Flow where the Scheduler, when run (or via a worker), triggers due Jobs. Indicate “execution flow” from the Scheduler to the Job executable (PHP scripts, raw commands, or callbacks).
- “OnlyOne” locking mechanism and the use of temporary directories (either default or custom) for avoiding job overlaps.
- Integration with external email services: upon execution of a job, its output can be redirected to files and then attached/emailed using SwiftMailer. Connect the Mailer trait/job configuration to an “Email Notification” component.

##### Architectural Patterns
- Separation of Concerns: The core scheduling logic (Scheduler), job definition (Job), and failure handling (FailedJob) are clearly separated, which suggests a modular design.
- Extensibility via Traits: The use of PHP traits for Interval and Mailer behaviors demonstrates a composable and reusable approach.
- Dependency Injection: External functionalities such as logging or sending emails are abstracted so that integrators can inject their own implementations.
- The design supports background and foreground execution paths, showing attention to asynchronous behavior and managing overlapping executions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    subgraph "Core Components"
        W("Worker (Cron Loop)"):::core
        S("Scheduler"):::core
        J("Job"):::core
        F("FailedJob"):::core
    end

    %% Job Enhancements
    subgraph "Job Enhancements"
        BH("Before Callback"):::hook
        AH("After Callback"):::hook
        I("Interval Trait"):::trait
        M("Mailer Trait"):::trait
        EN("Email Notification"):::external
    end

    %% External Dependencies & Configuration
    subgraph "External Dependencies & Configuration"
        CE("Cron Expression Library"):::external
        FS("File System (temp files)"):::external
        SM("SwiftMailer"):::external
        C("composer.json & CI/CD"):::config
        T("Tests"):::config
    end

    %% Relationships between Core Components
    W -->|"triggers"| S
    S -->|"creates/manages"| J
    J -->|"onFailure"| F

    %% Hook Callbacks
    BH -->|"pre-exec"| J
    J -->|"post-exec"| AH

    %% Job uses Traits
    J -->|"uses"| I
    J -->|"uses"| M

    %% Mailer Trait and Email Notification Flow
    M -->|"notifies"| EN
    EN -->|"sends-via"| SM

    %% Scheduler External Interactions
    S -->|"parses-schedule"| CE
    S -->|"uses-temp"| FS
    S -->|"configuredBy"| C

    %% Click Events
    click S "https://github.com/peppeocchi/php-cron-scheduler/blob/master/src/GO/Scheduler.php"
    click J "https://github.com/peppeocchi/php-cron-scheduler/blob/master/src/GO/Job.php"
    click F "https://github.com/peppeocchi/php-cron-scheduler/blob/master/src/GO/FailedJob.php"
    click I "https://github.com/peppeocchi/php-cron-scheduler/blob/master/src/GO/Traits/Interval.php"
    click M "https://github.com/peppeocchi/php-cron-scheduler/blob/master/src/GO/Traits/Mailer.php"
    click T "https://github.com/peppeocchi/php-cron-scheduler/tree/master/tests/"
    click C "https://github.com/peppeocchi/php-cron-scheduler/blob/master/composer.json"

    %% Styles
    classDef core fill:#aqua,stroke:#333,stroke-width:2px;
    classDef trait fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef hook fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#333,stroke-width:2px;
```
