Project Template Bundle Laravel Package

Getting Started

This is a 0.x package, so treat the public API as unstable and pin the version ("vandersangen/project-template-bundle": "0.8.16") until you've validated an upgrade.

1. Install with Composer and publish the package assets:

   composer require vandersangen/project-template-bundle:0.8.16
   php artisan vendor:publish --provider="Vandersangen\\ProjectTemplateBundle\\ProjectTemplateBundleServiceProvider"
   

2. Review the published config first — it is the map for everything else (queue connection, log model, cron registry, retention). Then open the RunCronMessage class and the queue_job_logs migration to understand the wire format and schema.
3. Run php artisan migrate and confirm the queue_job_logs table exists with run_id, status, output, and timestamp columns.
4. First use case: dispatch a RunCronMessage for a trivial command, keep a worker running (php artisan queue:work), and watch the row appear with status queued, flip to running, and accumulate live output. The runId you pass at dispatch time is your correlation key for the whole lifecycle.

The 0.8.16 release is the one that makes this workflow observable: cron output is written live into queue_job_logs, jobs are created with status queued, and runId is carried on RunCronMessage so you can trace a dispatch through to its output.

Implementation Patterns

• Dispatch with an explicit runId. Generate a UUID in your calling code (controller, scheduler, UI action) and pass it into RunCronMessage. Store that runId in your own domain table so you can join application records to queue logs later.
• Drive from the Laravel scheduler. Register cron definitions in the package's registry/config and let it dispatch RunCronMessage; avoid hand-rolling ->everyMinute() closures that bypass the package's logging.
• Model the status lifecycle. Expect queued → running → completed|failed. Treat queued as "accepted but no worker has picked it up" and use it to alert on stalled workers rather than as a success signal.
• Live output consumption. Poll the log row by runId from a dashboard, or hook Eloquent model events on the log model and broadcast updates. For CLI debugging, query the row directly:

  DB::table('queue_job_logs')->where('run_id', $runId)->value('output');
  

• Dedicated queue. Route cron messages to a named queue (->onQueue('crons')) with its own worker so long-running cron output doesn't starve interactive jobs.
• Custom commands. Implement the package's command contract and register in config rather than dispatching arbitrary shell strings; this keeps output capture and status transitions consistent.
• Retention. Schedule a pruning command or job that deletes queue_job_logs older than N days, indexed by run_id and status.

Gotchas and Tips

• queued never moving almost always means no worker on the right connection/queue. Check php artisan queue:failed and the queue connection in config before debugging the package.
• Live output can appear empty if the underlying command buffers stdout. Use unbuffered output (--no-ansi, flush after writes, or a PTY-based runner) — PHP's output buffering will otherwise hold everything until completion.
• runId collisions and retries. If a job is retried, verify whether the same runId produces a second log row or appends. Deduplicate on (run_id, attempt) in your queries until the behavior is documented.
• Message serialization size. RunCronMessage is serialized onto the queue; keep the payload to identifiers and cron metadata, not large argument blobs.
• Migration conflicts. Publish with --pretend first; the queue_job_logs table name is generic and may collide with an existing table.
• Log growth. Live output means rows get large fast. Add indexes on run_id and status immediately, and cap output length in the command implementation.
• Timezone. Cron evaluation follows config('app.timezone'); confirm this matches the schedule you intend, especially across DST boundaries.
• Extension points. The log model and queue connection are config-driven — override the model if you need extra columns, and listen to job lifecycle events rather than patching the package.
• 0.x instability. Pin the version and read each changelog before upgrading; RunCronMessage's constructor signature changed in this release with the addition of runId, so any custom dispatchers need auditing.