Scheduler Queues Api Laravel Package

Getting Started

This package is a thin presentation adapter: it exposes scheduler and queue operations over HTTP for the Liberu ecosystem. With zero stars, zero dependents, and no meaningful public documentation, treat the source code as the specification and budget time to read it before installing.

Minimal setup

composer require liberusoftware/scheduler-queues-api
php artisan vendor:publish --provider="Liberu\\SchedulerQueuesApi\\SchedulerQueuesApiServiceProvider"
php artisan route:list --path=api

If auto-discovery is not configured, register the provider manually in bootstrap/providers.php or config/app.php. Check composer.json for the actual namespace and Laravel version constraints before assuming compatibility.

Where to look first

1. composer.json — namespace, extra.laravel.providers, Illuminate version constraints.
2. src/Providers/*.php — what routes, config, migrations, and bindings are registered.
3. routes/api.php — the actual API surface: endpoints, middleware, prefixes.
4. config/*.php — queue connections, allowed commands, auth guards.
5. src/Http/Controllers and src/Http/Requests — validation and authorization behavior.
6. tests/ — the most reliable documentation if present.

First use case

Start with read-only observability, not mutation. Expose a small authenticated status endpoint that reports:

• Scheduled events and their next run times.
• Queue sizes per connection/queue.
• Recent failed jobs.

That gives immediate operational value without granting an HTTP caller the ability to flush queues or trigger the scheduler. Once you trust the adapter, add guarded mutation endpoints such as retrying a failed job or dispatching an allow-listed job class.

# Confirm routes and middleware before writing a client
php artisan route:list --path=api --columns=method,uri,name,middleware

Implementation Patterns

Treat it as an adapter, not a domain layer. Keep scheduler and queue logic in your application services; let the package controllers validate input and serialize output. If the package ships controllers you cannot easily extend, bind your own service behind its routes or wrap the endpoints with a gateway of your own.

Read-only queue status pattern

use Illuminate\Support\Facades\Queue;
use Illuminate\Support\Facades\DB;

final class QueueStatusService
{
    public function snapshot(array $allowedConnections): array
    {
        return collect($allowedConnections)->mapWithKeys(function (string $connection) {
            return [$connection => [
                'size' => Queue::connection($connection)->size(),
                'failed' => DB::table('failed_jobs')
                    ->where('connection', $connection)
                    ->count(),
            ]];
        })->all();
    }
}

Expose only connection names from a config allowlist. Never accept an arbitrary connection or queue name from the request and pass it straight to Queue::connection().

Scheduler inspection pattern

use Illuminate\Console\Scheduling\Schedule;

public function index(Schedule $schedule)
{
    $events = collect($schedule->events())->map(fn ($event) => [
        'command' => $event->command,
        'expression' => $event->expression,
        'description' => $event->description,
        'next_run' => $event->nextRunDate()->toIso8601String(),
        'without_overlapping' => (bool) $event->withoutOverlapping,
    ]);

    return response()->json(['data' => $events]);
}

Guard mutation endpoints explicitly. Scheduler and queue APIs are effectively remote administration. Use a dedicated admin guard or ability, not the default user session.

Route::middleware(['auth:sanctum', 'can:manage-queues'])
    ->prefix('api/ops')
    ->group(function () {
        Route::get('/queues', [QueueStatusController::class, 'index']);
        Route::post('/failed-jobs/{id}/retry', [FailedJobController::class, 'retry']);
    });

Allow-list commands and job classes. If the package offers a “run command” or “dispatch job” endpoint, back it with a config-driven map rather than accepting a class or command string from the client.

// config/scheduler-queues-api.php
return [
    'allowed_connections' => ['redis', 'database'],
    'allowed_jobs' => [
        'reports' => \App\Jobs\GenerateReport::class,
    ],
];

Use Laravel primitives beneath the adapter. For retries and flushes, prefer Artisan::call('queue:retry', ['id' => $id]) or direct failed_jobs operations over shelling out. For dispatching, use Bus::dispatch() so middleware, tenancy, and tracing apply consistently.

Multi-tenant and multi-connection setups. Scope queue sizes and failed-job counts by tenant where your schema supports it. Do not leak connection names, hostnames, or serialized payloads in responses.

Testing pattern

Queue::fake();
Bus::fake();

$this->actingAs($admin)
    ->postJson('/api/ops/failed-jobs/1/retry')
    ->assertOk();

Bus::assertDispatched(GenerateReport::class);

Use Queue::fake() and Bus::fake() for dispatch assertions, and Http::fake() only if the adapter itself makes outbound calls. Test authorization failures explicitly — they are the highest-risk paths.

Audit everything. Listen to the package’s events if it emits them; otherwise wrap mutation endpoints with your own listener or middleware that records actor, endpoint, target, and timestamp.

Gotchas and Tips

License is NOASSERTION. This is the biggest blocker. There is no clear grant of rights. Get legal review before shipping it in a commercial product, and consider isolating it behind an internal interface so it can be replaced.

The release date is suspicious. A last release of 2026-10-26 is future-dated relative to normal package lifecycles. Verify the tag, the commit history, and the Composer metadata. Pin an exact version and commit hash, and review the diff before upgrading.

Zero dependents means zero field testing. Expect rough edges: missing config defaults, hard-coded middleware, unclear error responses, and no upgrade guide. Fork or vendor the package if you need stability, and keep your integration behind a small internal adapter.

Do not trigger schedule:run from a web request casually. It runs every due event, can exceed request timeouts, and may overlap with cron. If you must expose it, restrict it to admins, use a queue or background process, and ensure withoutOverlapping() and onOneServer() locks are in place. The normal production path is still system cron or a supervisor-managed scheduler.

Queue mutation endpoints are destructive. queue:flush, queue:clear, and bulk retries can erase evidence or cause thundering herds. Gate them separately from read endpoints, require confirmation parameters, rate-limit them, and log the actor.

Long-running operations do not belong in HTTP. queue:work and queue:listen should run under Supervisor or Horizon, not through an API call. If the package exposes worker controls, treat them as signals to your process manager, not as direct process spawns.

Route and config caching. If the package registers closures or reads env() outside config files, php artisan route:cache or config:cache may break it. Test both in staging. Publish and review config before caching.

Middleware and auth assumptions. Check whether routes are registered with api middleware only. Adding auth:sanctum after the fact is easy, but verify the package does not also register public health or debug routes you did not intend to expose. Run php artisan route:list and diff it against expectations on every upgrade.

Serialized failed-job payloads. Failed jobs contain the serialized command and potentially sensitive data. Return only IDs, job names, exception classes, and timestamps unless the caller has explicit permission to see payloads.

Compatibility drift. Confirm the package supports your Laravel and PHP versions, especially if you are on Laravel 11/12 and the package targets older Illuminate contracts. Check illuminate/support, illuminate/queue, and illuminate/console constraints.

Debugging checklist

php artisan about
php artisan route:list --path=api -v
php artisan config:show scheduler-queues-api
tail -f storage/logs/laravel.log

Use Telescope or Horizon if available to inspect the actual queue and scheduled-event behavior. For HTTP failures, isolate whether the issue is routing, middleware, authorization, validation, or the underlying queue connection.

Extension points to prefer. Publish the config, bind your own implementations over the package’s interfaces, and listen to Laravel’s native queue/scheduler events (JobProcessing, JobFailed, ScheduledTaskFinished) rather than relying on undocumented package hooks. If the package emits no events, add your own middleware around its routes — that is the most stable integration surface you have.