README

Simple, dependency-free PHP background job runner using filesystem queues.

🚀 Quick Start

1. Create a Task Class

Any PHP class can be a job. No interface required.

// src/Tasks/EmailTask.php
namespace App\Tasks;

class EmailTask {
    public function __construct(private string $apiKey) {}

    public function send(string $to, string $subject): void {
        // Send email logic...
        echo "Email sent to $to";
    }
}

2. Enqueue a Job (Programmatic)

Use this in your application (Controller, Service, etc) to dispatch jobs.

use MithrilExecutor\Queue\FileJobQueue;
use MithrilExecutor\ValueObjects\Job;
use App\Tasks\EmailTask;

// Setup
$queue = new FileJobQueue(__DIR__ . '/storage');

// Create Job
$job = new Job(
    id: uniqid('job-'),
    className: EmailTask::class,
    constructorArgs: ['my-api-key'], // Passed to __construct
    calls: [
        [
            'method' => 'send', 
            'args' => ['user@example.com', 'Welcome!'] // Passed to method
        ]
    ]
);

// Dispatch
$queue->enqueue($job);

3. Run the Worker (Terminal)

Start the supervisor to process jobs.

php bin/mithril daemon --bootstrap=example/bootstrap.php --concurrency=4 --memory=128M

🛠 CLI Reference & Flags

Global Flags (Available for most commands)

daemon

Starts the worker loop (supervisor). Recommended for production.

Example:

# Runs 5 workers, each limited to 128MB RAM, loading classes from bootstrap.php
php bin/mithril daemon --concurrency=5 --memory=128M --bootstrap=src/bootstrap.php

list

Lists jobs in the queue.

Example:

# Export all failed jobs to a CSV file
php bin/mithril list --status=failed --format=csv --output=failed_jobs.csv

work

Processes a single job and exits. Useful for cron jobs or one-off tasks.

Example:

php bin/mithril work --memory=512M --quiet --bootstrap=autoload.php

run

Executes a specific job file directly (bypassing the queue logic). Useful for debugging a failed job file manually.

Example:

php bin/mithril run --file=/path/to/storage/queue/failed/job-123.json --bootstrap=autoload.php

enqueue

Enqueue a job via CLI (useful for testing).

Example:

php bin/mithril enqueue \
  --class="App\Tasks\EmailTask" \
  --ctor='["api-key"]' \
  --calls='[{"method":"send","args":["thales@example.com","Hello"]}]'

📂 Directory Structure

• bin/mithril: The CLI executable.
• storage/queue: Where pending/running/done jobs are stored as JSON.
• src/: The library source code.
• example/: Demo files.