GitHub
Luminova Framework
Toggle Theme
Version

Background Task Queue - Novakit CLI Management

Last updated: 2025-07-24 07:23:02

Novakit commands to run, monitor, and manage background tasks. Like sending emails or cleaning up files without affecting your app’s performance. Tasks are executed safely in the background.

The Background Task Queue in Novakit provides helper commands for working with the Luminova\Base\BaseTaskQueue class. It allows you to stage and run background tasks efficiently using a queue system that supports:

  • Delayed execution
  • Retries on failure
  • Task priority levels
  • Recurring tasks (e.g., daily or hourly)

The CLI TaskQueue commands let you manage queued tasks directly from the terminal. You can:

  • Add new tasks to the queue
  • Pause, retry, or inspect existing tasks
  • Run a background task worker using cron
  • Monitor task execution and performance

For setup instructions and full setup examples, see the Background Task Queue System documentation.

List of Commands

task:init       Initialize the task queue system and create the required table in your database.
task:deinit     Remove the task queue table and all tasks.
task:queue      Add a new task to the queue.
task:list       Show tasks in the queue. You can filter by status or ID.
task:info       Show full information of a task by ID.
task:delete     Delete a task from the queue.
task:purge      Clear all tasks with a specific status (like completed).
task:pause      Pause a task. It will not run until resumed.
task:resume     Resume a paused task.
task:retry      Set a failed task back to pending.
task:status     Manually change a task\'s status.
task:run        Start a worker that processes tasks in the queue.
task:sig        Send control signals to the task worker (stop or resume).
task:listen     Show real-time logs while tasks are being processed.
task:export     Export all tasks from the queue with optional status filtering.

Task Status List

You can use these values to filter or update task status:

StatusTypeDescription
allstringIncludes tasks of all statuses.
foreverstringTask runs again and again. It will not be auto-deleted.
pendingstringTask is waiting in the queue.
pausedstringTask is paused. It will not run until resumed.
runningstringTask is now being processed.
failedstringTask failed. Usually caused by an error or exception.
completedstringTask ran successfully. It may be deleted if configured.

Custom Task Handler Class

You can use --class (or -c) in any command to choose your own task handler class. If not set, it will use this default class:

namespace App\Tasks\TaskQueue;

Examples:

php novakit task:list --class=App\\Tasks\\MyTask
php novakit task:list -c=App\\Tasks\\MyTask

Command Help

To show all task-related commands:

php novakit task --help

To see help for one command:

php novakit task:list --help

Task Table Setup

Create the Table

Use this the first time you use the task system:

php novakit task:init

Delete the Table

This removes all tasks and deletes the task table:

php novakit task:deinit

Adding Tasks to the Queue

Add a task from your default tasks method:

php novakit task:queue

Add a specific class method:

# Using instance method (@)
php novakit task:queue \
  --task=App\\Utils\\Worker@clean \
  --args='["temp"]' \
  --priority=1 \
  --schedule='+10 minutes'

# Using static method (::)
php novakit task:queue \
  --task=App\\Utils\\Worker::clean \
  --args='["temp"]' \
  --priority=1 \
  --schedule='+10 minutes'

Option guide:

  • --task or -t: The method to run (example: Class@method or Class::method)
  • --args or -a: List of parameters as a JSON string
  • --schedule or -s: When to run (e.g. +10 minutes)
  • --priority or -p: Number from 0–100 (higher runs earlier)

Adding Tasks in Code (Programmatic Usage)

You can also add tasks inside your code:

$arguments = ['temp'];
$schedule = '+10 minutes';
$priority = 1;

// Static method
TaskQueue::enqueue(App\Utils\Worker::class . '::clean', $arguments, $schedule, $priority);

// Instance method
TaskQueue::enqueue(App\Utils\Worker::class . '@clean', $arguments, $schedule, $priority);

// Or Invokable Class that implements Interface (Luminova\Interface\QueueableInterface)
TaskQueue::enqueue(App\Utils\Worker::class, $arguments, $schedule, $priority);

CLI vs Code Usage

FeatureCLI ExampleCode Example
ContextTerminal, cron jobsPHP scripts, controllers, events
Method format-t Class@method or Class::method'Class@method' or 'Class::method'
Arguments formatJSON stringPHP array
Schedule formatString (e.g. +10 minutes, UNIX timestamp)Same as string (DateTimeInterface\|string\|int\|null)
When to useManual or scheduled queueQueue tasks inside your application flow

Running the Task Worker

To start processing queued tasks:

php novakit task:run

Or use a custom PHP script:

php path/to/project/bin/TaskRunner.php

Using Cron to Run Tasks Automatically

To run the worker every minute:

* * * * * /usr/bin/php /path/to/project/novakit task:run >> /path/to/logs/task.log 2>&1

You can also add more options:

* * * * * \
  /usr/bin/php /path/to/project/novakit task:run \
  --class=App\\Tasks\\UserTaskQueue \
  --limit=10 \
  --sleep=200000 \
  --idle=3 \
  --output=debug >> /var/log/task_worker.log 2>&1

Explanation:

  • --limit=10: Process 10 tasks at most in one loop
  • --sleep=200000: Wait 0.2 seconds between each loop
  • --idle=3: Stop after 3 loops with no tasks
  • --output=debug: Show debug logs or write to file

To check your PHP path:

which php

Avoid Running the Worker Twice

Sometimes a task worker may still be running when another one starts. To stop this, use a locking system.

Using flock with Cron

This prevents overlapping (recommended):

* * * * * flock -n /tmp/task.lock /usr/bin/php /path/to/project/novakit task:run

Using --flock-worker with Novakit

This will create a custom flock file preventing overlapping.

* * * * * /usr/bin/php /path/to/project/novakit task:run --flock-worker

Using a Stop Signal File

You can also create a stop signal file that pauses execution until manually deleted.

Or by running sig command to create signal or remove lock:

php novakit task:sig --stop-worker
php novakit task:sig --resume-worker

Note: You can define your own stop file by setting $stopSignalFile in your task handler.

Next » Cron Task Scheduling
On this page