README

A robust, shared-hosting-friendly asynchronous task runner for Laravel.

This package provides a database-backed, cron-driven, retryable, idempotent async task system. It is specifically architected for environments where traditional queue workers (like Supervisor + php artisan queue:work or Redis/Horizon) cannot run continuously. Perfect for cPanel, DirectAdmin, or strictly restricted shared hosting setups.

🚀 When to use this package

• You are on a shared host with strict background process limits and no daemonizing tools like Supervisor.
• You only have Cron access.
• You want a lightweight database-first queue with absolutely zero extra infrastructure or Redis required.

⚠️ When NOT to use this package

• You need true sub-second real-time processing (use Redis/Beanstalkd instead).
• You have heavy, long-running CPU-bound tasks like video encoding or FFmpeg.
• You are already using Laravel Horizon successfully.

📦 Installation

Require the package via composer:

composer require fahriar/laravel-shared-queue

Publish the configuration file and database migrations:

php artisan vendor:publish --tag=shared-queue-config
php artisan vendor:publish --tag=shared-queue-migrations

Run the database migrations to create the shared_queue_tasks table:

php artisan migrate

🛠️ Setup & Configuration

Define your tasks inside config/shared-queue.php. Here you map simple string types to concrete classes:

'tasks' => [
    'send_invoice_email' => \App\Tasks\SendInvoiceEmailTask::class,
    'process_payment'    => \App\Tasks\ProcessPaymentTask::class,
],

Create a Task Handler

Your handlers must implement the LaravelSharedQueue\Contracts\TaskHandler contract. It natively supports Laravel's Container, so dependency injection in the constructor works perfectly:

namespace App\Tasks;

use LaravelSharedQueue\Contracts\TaskHandler;
use Illuminate\Support\Facades\Log;

class SendInvoiceEmailTask implements TaskHandler
{
    public function handle(array $payload): void
    {
        // Business logic here.
        Log::info("Sending email for invoice: " . $payload['invoice_id']);
    }
}

Keep your task handlers idempotent and bite-sized. Let the database act as the state engine!

⚡ Dispatching Tasks

You can dispatch tasks seamlessly using the injected Facade or the global helper function.

Basic Dispatch

use LaravelSharedQueue\Facades\SharedQueue;

SharedQueue::dispatch('send_invoice_email', [
    'invoice_id' => 1001,
]);

// Or securely dispatch using the global helper:
shared_queue('send_invoice_email', ['invoice_id' => 1001]);

Delayed Tasks

Need to process something in the future? Pass an explicit delay:

SharedQueue::dispatch('send_invoice_email', ['invoice_id' => 1001], [
    'delay' => now()->addMinutes(10) // Also accepts integer seconds
]);

Idempotency (Prevent Duplicate Jobs)

If you operate in high-traffic or looping scripts, protect against identical tasks firing simultaneously:

SharedQueue::dispatch('process_payment', ['order_id' => 5], [
    'idempotency_key' => 'payment_order_5'
]);

If a pending or processing task already exists with this key, the dispatch safely ignores the request to avoid duplicates.

Dispatch After Database Commit

Only dispatch the task if the outer database transaction officially commits:

SharedQueue::dispatchAfterCommit('send_invoice_email', ['invoice_id' => 1001]);

This safely waits until the active DB transaction commits before finally inserting the task queue row.

⚙️ Running the Worker

Since this is built explicitly for shared hosting systems, you run the queue worker natively via Laravel's scheduled cron job engine.

In your routes/console.php (Laravel 11+) or app/Console/Kernel.php (Laravel 10):

use Illuminate\Support\Facades\Schedule;

Schedule::command('shared-queue:work')->everyMinute()->withoutOverlapping();

Make sure your server/cPanel cron is set to trigger your application schedule every minute natively:

* * * * * cd /home/youruser/public_html && php artisan schedule:run >> /dev/null 2>&1

Once running, the worker runs batch checks and operates securely utilizing robust database row-locking tools (skipLocked() / lockForUpdate()) to ensure no race conditions overlap.

🧰 Managing Tasks (CLI)

The package provides a suite of helpful Artisan commands to inspect your queue:

# View all recent tasks in a neat table representation
php artisan shared-queue:list

# Retry a specifically failed or dead task
php artisan shared-queue:retry {id}

# Retry all failed/dead tasks simultaneously
php artisan shared-queue:retry --all-dead

# Delete old successfully "completed" tasks (clears out database bloat)
php artisan shared-queue:prune

# Completely wipe tasks marked permanently as "dead"
php artisan shared-queue:flush-dead

🧪 Testing (For Contributors)

To run the internal unit and feature test suite ensuring 100% stable compatibility:

composer run test
# OR
./vendor/bin/phpunit

🔒 Security Vulnerabilities

If you discover a security vulnerability within this package, please e-mail Fahriar Ahammed via fahriar.ahammed@outlook.com. All security vulnerabilities will be promptly addressed.

📝 License

The Laravel Shared Queue package is open-sourced software licensed under the MIT license.