Cron Bundle Laravel Package

Getting Started

• Install with composer require m-h-1/cron-bundle. Despite the Laravel context, this ships as a bundle — expect Symfony-style naming and bootstrapping rather than Laravel package auto-discovery. Check composer.json for extra.laravel.providers first; if there isn't one, you'll register the service provider (or drive the runner class) manually in config/app.php / a small custom provider.
• Look at three places before writing code: (1) the bundle's config file (cron entries, lock store, PHP binary), (2) the console command that evaluates due entries and dispatches them, (3) the LockFactory usage introduced in v1.3.0 — that's the piece that now guards against overlapping runs.
• First use case: replace a hand-maintained crontab with a single system cron line that invokes the runner every minute, and let the bundle decide which entries are due. Pair that with the new php path setting so the runner executes jobs with the same binary your app expects:

  * * * * * cd /var/www/app && /usr/bin/php8.3 vendor/bin/<runner> >> /var/log/cron-bundle.log 2>&1
  

• Sanity check on day one: run the runner manually with verbose output, confirm it lists due entries, confirm a second concurrent invocation is blocked by the lock, then wire it into system cron.

Implementation Patterns

• One crontab line, many entries. Keep scheduling logic in the bundle config (or a PHP array/attribute-based definition) and leave the OS crontab minimal. This makes schedules reviewable in PRs and portable across environments.
• Bridge into the Laravel scheduler when you already have one. Rather than running two schedulers, invoke the bundle runner from app/Console/Kernel.php:

  $schedule->exec('/usr/bin/php8.3 vendor/bin/<runner>')
           ->everyMinute()
           ->withoutOverlapping()
           ->runInBackground();
  

  Keep withoutOverlapping() here as a coarse safety net and let the bundle's own lock handle per-job granularity.
• Custom PHP path (v1.3.0) is the answer to multi-version hosts. Containers with a different CLI binary than FPM, Herd/Valet/Sail setups, or hosts where /usr/bin/php is 7.4 but the app needs 8.3 — set the binary explicitly instead of relying on PHP_BINARY inheritance. Drive it from env:

  'php' => env('CRON_BUNDLE_PHP', PHP_BINARY),
  

  Never commit a host-specific absolute path; make it per-environment.
• Size lock TTLs to your longest realistic runtime. A lock that expires mid-run defeats the purpose; a lock that lives too long leaves jobs skipped after a crash. Set TTL per entry where the bundle allows it, and make it comfortably longer than p95 runtime.
• Treat exit codes and output as first-class. Pipe runner output to a log and alert on non-zero exits; a silent cron failure is the classic way a bundle like this bites you in production.
• Config-cache discipline. If you drive this from a Laravel provider, remember php artisan config:cache will freeze your cron config — always re-cache on deploy, and don't compute entries from runtime state (DB rows, request data) inside the config file.

Gotchas and Tips

• v1.3.0 replaced the lock trait with direct use of the lock component. Mostly internal, but it's a breaking change if you extended the trait, overrode its methods, or relied on lock behaviour being opt-in per entry. Grep your codebase for the trait name before upgrading, and re-verify that jobs you expected to overlap now don't (and vice versa).
• The lock store matters more than the lock. flock-style locks are per-host — with two app servers you get two concurrent runs. Use a shared store (Redis/database) whenever you scale horizontally, and confirm the bundle reads that store from config rather than defaulting to a local file.
• The custom PHP path is shell-sensitive. It must be absolute, executable by the cron user (not your SSH user), and free of spaces or shell metacharacters — if the bundle interpolates it into a command string, a path like /opt/php 8.3/bin/php will silently break. Verify with sudo -u www-data /path/to/php -v.
• Two schedulers, two sources of truth. If you also have Laravel's schedule:run firing the same commands, you'll double-run. Pick one owner per job and document it.
• Timezones. Cron expressions are normally evaluated in the server's timezone; a container running UTC against a team thinking in local time produces "why did the 02:00 job run at 10:00" tickets. Set the timezone explicitly in config if supported.
• Debugging recipe: run the runner by hand as the cron user, check the lock files/keys before and after, and inspect whether the overlap guard or the cron expression is what's skipping your job — those two failure modes look identical in logs.
• Extension points worth knowing: the binary-path config, the lock factory/store, and the entry definition format. If you need custom behaviour (retries, notifications on failure), wrapping the runner command is usually cleaner than forking the bundle — this is a small package with a correspondingly small surface area, so expect to write glue rather than find a hook.