README

A dev-only visual builder for cron expressions. Fill in minute/hour/day/month/weekday, and get instantly: the resulting expression, a human-readable description, the next 5 times it would run, and a ready-to-paste #[Cron(...)] snippet.

Structure

cronbuilder-package/
├── composer.json
├── README.md
└── src/
    ├── NeoCronBuilderPackage.php
    ├── Middleware/
    │   └── DevOnlyMiddleware.php
    ├── Service/
    │   └── CronExpressionCalculator.php
    ├── Controllers/
    │   └── CronBuilderController.php
    ├── Assets/
    │   ├── css/cronbuilder.css
    │   └── js/cronbuilder.js
    └── Templates/
        └── pages/
            └── builder.html.twig

Dev-only, by design

Every route this package exposes is protected by DevOnlyMiddleware, which checks Config/app.config.php's environment key. Outside environment: dev, every route returns a blocked response. This tool only helps you write cron expressions correctly — it has no reason to ever be reachable on a live site.

Installation

php bin/neo package:require neophp/cronbuilder-package --project=MyProject

Register it in the project's Config/app.config.php:

return [
    // ...
    'packages' => [
        \Vendor\NeoPHP\CronBuilderPackage\NeoCronBuilderPackage::class,
    ],
];

No configuration file, no migration.

Usage

Visit /_cronbuilder/ (only reachable in dev):

1. Use a preset (every minute, every hour, every weekday at 9 AM, etc.) or fill in each field manually
2. The expression, its description, and the next 5 run times update automatically as you type
3. Copy the expression, or copy the full #[Cron(...)] snippet directly from the code block
4. Paste it into your own class:

use Neo\Core\Cron\Attribute\Cron;

#[Cron(expression: '0 9 * * 1-5')]
final class MyScheduledTask
{
    public function handle(): void
    {
        // ...
    }
}

This package never writes to your files — it only helps you build the string, exactly like neo-formbuilder-package generates code to copy-paste rather than writing it for you.

CronExpressionCalculator

Also usable directly in PHP, outside the UI:

use Vendor\NeoPHP\CronBuilderPackage\Service\CronExpressionCalculator;

$calculator->describe('0 9 * * 1-5');
// "Runs every weekday at 09:00"

$calculator->getNextRuns('0 9 * * 1-5', 5);
// ['2026-08-10 09:00', '2026-08-11 09:00', ...]

Known limitations

• Custom-built cron parser, not a full implementation of the cron standard. It correctly handles *, fixed values, ranges (1-5), lists (1,3,5), and steps (*/15) — the vast majority of real-world expressions. It does not implement the traditional Unix cron quirk where day-of-month and day-of-week are combined with OR logic when both are restricted (most modern schedulers, including this one, treat them as AND for simplicity and predictability).
• getNextRuns() iterates minute by minute with a one-year safety cap — fine for interactive use in the builder UI, not intended as a general-purpose scheduling engine for production task execution.
• Descriptions are limited to a few common patterns (every N minutes, every day at a fixed hour, every weekday at a fixed hour). Anything else falls back to a literal field-by-field description rather than fully natural language.

License

MIT