CLI Commands

The package supplies several Spark commands to orchestrate scheduling, queue consumption and introspection.

Cron / Scheduler

Command

Description

jobs:cronjob:run

Execute all due scheduled jobs immediately.

jobs:cronjob:history <name> [--extended]

Show recent executions (extended adds attempt, queue, payload hash, etc.).

jobs:cronjob:enable <name>

Enable a scheduled job by name.

jobs:cronjob:disable <name>

Disable a scheduled job by name.

jobs:cronjob:list

List registered cron jobs and their expressions.

Commands

jobs:cronjob:list

> php spark jobs:cronjob:list

This will list all available tasks that have been defined in the project, along with their type and the next time they are scheduled to run.

+--------------------------+---------+-------------+---------------------+---------------------+
| Name                     | Type    | Expression  | Last Run            | Next Run            |
+--------------------------+---------+-------------+---------------------+---------------------+
| job1                     | command | 08 10 * * * | --                  | 2022-11-04 10:08:00 |
| Job2                     | command | 0 0 * * *   | 2022-10-28 13:23:21 | 2022-11-05 00:00:00 |
+--------------------------+---------+-------------+---------------------+---------------------+

jobs:cronjob:disable

> php spark jobs:cronjob:disable

Will disable the task runner manually until you enable it again. Writes a file to {WRITEPATH}/cronJob so you need to ensure that directory is writable. Default CodeIgniter permissions already have the WRITEABLE path with write permissions. You should not need to change anything for this to work.

jobs:cronjob:enable

> php spark jobs:cronjob:enable

Will enable the task runner if it was previously disabled, allowing all tasks to resume running.

jobs:cronjob:run

> php spark jobs:cronjob:run

Queues

Command

Description

jobs:queue:run [--queue=NAME] [--oneTime] [--background]

Run a worker consuming jobs from the configured backend.

jobs:queue:purge [--status=...] [--queue=...] [--before=...] [--dry-run] [--force]

Purge completed/failed records from the database queue table.

jobs:redis:reap-stuck [--queue=NAME] [--timeout=SECONDS]

Re-enqueue Redis jobs left in the processing list past the visibility timeout (v1.1+).

jobs:health [--json] [--queue=NAME]

Display system health and queue statistics.

Queue Worker Details

The jobs:queue:run command starts a long-running process that:

  1. Uses QueueManager to get the configured queue backend

  2. Continuously calls watch() to fetch jobs

  3. Executes jobs via JobLifecycleCoordinator

  4. Handles retries, metrics, and logging

  5. Sleeps between cycles (default: 1 second)

Options:

  • --queue=NAME - Specific queue name to consume from (default: uses first in config)

  • --sleep=N - Seconds to sleep between fetch cycles (default: 1)

Queue Backends: The worker automatically uses the backend configured in Config\Jobs::$worker:

  • redis - Fast in-memory queue with delayed job support

  • database - Persistent relational storage

  • beanstalk - Beanstalkd tube-based processing

  • servicebus - Azure Service Bus integration

  • sync - Inline execution (no background processing)

Background Worker (detached)

The jobs:queue:run command supports starting the worker in the background so it can run independently of the shell session.

  • Option: --background — spawn a detached worker process and return immediately to the caller.

Implementation notes:

  • The worker is spawned using a platform-appropriate detached invocation: nohup + & on POSIX systems, and start /B on Windows. Standard output and error are redirected to the system null device to avoid writing to a closed CLI stream.

  • The child is invoked with --queue=<name> so it does not prompt interactively for the queue name.

PHP executable selection:

  • When running from the CLI (php spark ...) the system PHP binary is used (PHP_BINARY).

  • When the worker is started from a non-CLI SAPI (for example, from a web request or a supervisor that does not provide a proper PHP path), you can configure the PHP binary path using the PHP_BINARY_PATH environment variable. Set it to the absolute path of your php executable, for example:

    • POSIX: export PHP_BINARY_PATH=/usr/bin/php

    • Windows (PowerShell): $env:PHP_BINARY_PATH = 'C:\\php\\php.exe'

You can also set PHP_BINARY_PATH inside your framework project’s .env file so it’s available to the application at runtime. Example .env entry:

PHP_BINARY_PATH=/usr/bin/php

Notes and recommendations:

  • Ensure the spark script is accessible and executable from the working directory used when spawning the background process (the implementation uses the project spark script by path).

  • Because the background child runs detached and has its stdout/stderr redirected, any early startup errors are captured in a brief trace file under the Jobs log directory (see config('Jobs')->filePath). Check that location if a background child exits immediately.

  • For more advanced background supervision consider using a process manager (systemd, Supervisor, or equivalent) instead of ad-hoc detaching.

Metrics: If metrics are enabled, the worker tracks:

  • jobs_fetched - Total fetch attempts

  • jobs_age_seconds - Queue latency (enqueue → start)

  • jobs_exec_seconds - Execution duration

  • jobs_succeeded / jobs_failed / jobs_requeued / jobs_failed_permanently

  • jobs_timed_out (v1.0.3+, both pcntl and fallback paths)

  • jobs_dlq_failed (v1.0.3+, DLQ unavailable or push failed)

  • Plus queue-level metrics if using InstrumentedQueueDecorator

Worker maintenance (v1.2+):

  • Every 100 iterations the worker pings the database with SELECT 1 and reconnects on failure (avoids MySQL has gone away after wait_timeout).

  • Every 1 000 iterations the in-memory metrics collector is reset and gc_collect_cycles() is invoked so workers running 24/7 keep memory bounded.

  • When blockingFetch = true and the active worker is redis or beanstalk, the pollInterval sleep is skipped because the fetch already blocked.

Redis reaper (v1.1+)

jobs:redis:reap-stuck walks the Redis processing-meta hash and re-enqueues every item whose lease is older than the visibility timeout. Run it periodically via system cron when Redis is the active worker:

# every minute, default visibility timeout (Config\Jobs::$redisProcessingVisibilityTimeout, 300s)
* * * * * php /path/to/spark jobs:redis:reap-stuck --queue=default

# override the timeout from the CLI
php spark jobs:redis:reap-stuck --queue=high --timeout=120

A worker that crashes after watch() but before removeJob() leaves its message in the processing list. Without the reaper that message is invisible to the rest of the workers; with it the message is restored to waiting after the configured timeout and retried.

Health Monitoring

jobs:health

> php spark jobs:health

Displays comprehensive system health and queue statistics.

Options:

  • --json - Output in JSON format (machine-readable)

  • --queue=NAME - Show statistics for a specific queue only

Example Output (table format):

=== Jobs System Health Check ===

Configuration:
  Retry Strategy: exponential (base: 60s, multiplier: 2.0, max: 3600s)
  Job Timeout: 300 seconds
  Dead Letter Queue: failed_jobs
  Rate Limits: default=50/min, high_priority=100/min

Queue: default
  Status:
    Pending: 42
    Processing: 3
    Completed: 1,245
    Failed: 12
  Rate Limit: 23/50 (46% used)
  Last 24h:
    Executions: 156
    Success Rate: 92.3%
    Failure Rate: 7.7%
    Avg Duration: 2.45s

JSON Output (--json):

{
  "config": {
    "retry_strategy": "exponential",
    "job_timeout": 300,
    "dead_letter_queue": "failed_jobs",
    "rate_limits": {"default": 50}
  },
  "queues": {
    "default": {
      "status": {"pending": 42, "processing": 3, "completed": 1245, "failed": 12},
      "rate_limit": {"current": 23, "max": 50},
      "last_24h": {
        "executions": 156,
        "success_rate": 92.3,
        "avg_duration_seconds": 2.45
      }
    }
  }
}

Use Cases:

  • Monitoring dashboards (JSON output to Prometheus/Grafana)

  • Quick operational health checks

  • Identifying bottlenecks and failure patterns

  • Rate limit capacity planning

Examples

Run Redis worker on specific queue:

php spark jobs:queue:run --queue=emails --sleep=2

View extended cron history:

php spark jobs:cronjob:history <name> --extended

Disable a cron job:

php spark jobs:cronjob:disable