Code e job - Knowledge of Laravel

Cosa sono le code

Nelle applicazioni web puoi avere operazioni che richiedono qualche secondo: invio email, ridimensionamento immagini, chiamate ad API esterne. Eseguirle sincronamente in una richiesta HTTP costringe l’utente ad aspettare. Con le code di Laravel esegui questi lavori in background in modo asincrono. La richiesta risponde subito e i worker si occupano del lavoro.

Le code supportano più backend: database, Redis, Amazon SQS, ecc. In sviluppo, con il driver sync i job vengono eseguiti immediatamente senza coda.

Configurazione delle code

config/queue.php

Impostazioni in config/queue.php. Cambia driver con QUEUE_CONNECTION.

'default' => env('QUEUE_CONNECTION', 'database'),

.env

QUEUE_CONNECTION=database

# Redis
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

Preparazione del driver database

Serve una tabella jobs. In Laravel 11+ è già inclusa nella migration. Altrimenti:

php artisan make:queue-table
php artisan migrate

Preparazione del driver Redis

Aggiungi la connessione in config/database.php e installa il driver.

composer require predis/predis

SQS Overflow Storage

Amazon SQS ha un limite sulla dimensione dei payload. Per job con payload grandi puoi salvare l’eccesso in un cache store e inviare solo un puntatore.

'sqs' => [
    // ...
    'overflow' => [
        'enabled' => env('SQS_OVERFLOW_ENABLED', false),
        'store' => env('SQS_OVERFLOW_STORE'),
        'always' => false,
        'delete_after_processing' => true,
        'flush_on_clear' => env('SQS_OVERFLOW_FLUSH_ON_CLEAR', false),
    ],
],

enabled attivo: payload > 1MB salvati nel cache store.
always a true: salva sempre nel cache store.
delete_after_processing (default true): elimina i payload salvati al successo.
flush_on_clear a true: queue:clear esegue flush dello store di overflow. Usa uno store dedicato.

Creazione della classe job

make:job

php artisan make:job SendWelcomeEmail

Genera app/Jobs/SendWelcomeEmail.php.

Struttura del job

<?php

namespace App\Jobs;

use App\Models\User;
use App\Mail\WelcomeMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public User $user,
    ) {}

    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

ShouldQueue indica che va elaborato via coda. Il trait Queueable fornisce i metodi necessari.

Passando un modello Eloquent al costruttore, Laravel serializza solo l’ID e ricarica i dati aggiornati in fase di esecuzione: payload più leggeri.

Dispatch del job

dispatch()

use App\Jobs\SendWelcomeEmail;

public function register(Request $request): RedirectResponse
{
    $user = User::create($request->validated());

    SendWelcomeEmail::dispatch($user);

    return redirect('/dashboard');
}

Ritardato

SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

dispatchAfterResponse()

Esegui subito dopo la risposta HTTP. Funziona anche con sync.

SendWelcomeEmail::dispatchAfterResponse($user);

Coda specifica

SendWelcomeEmail::dispatch($user)->onQueue('emails');

Queue Routing

Instrada per default certi job a una connessione/coda tramite Queue::route() nel boot() di un ServiceProvider.

use App\Concerns\RequiresVideo;
use App\Jobs\ProcessPodcast;
use App\Jobs\ProcessVideo;
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts');
    Queue::route(RequiresVideo::class, queue: 'video');
}

Puoi indicare interfacce, trait o classi genitore. Più job insieme:

Queue::route([
    ProcessPodcast::class => ['redis', 'podcasts'], // connection e queue
    ProcessVideo::class => 'videos',                // solo queue (usa la connessione di default)
]);

Il Queue Routing è sovrascrivibile a livello di job con onQueue() / onConnection().

Inoltro delle code (`Queue::forward()`)

Con Queue::forward() puoi inoltrare i job da una coda a un’altra coda o connessione. È utile quando vuoi cambiare l’infrastruttura delle code senza modificare i singoli job o il codice chiamante.

use Illuminate\Support\Facades\Queue;

Queue::forward('reports', 'reports.fifo', 'sqs');
Queue::forward('payments', connection: 'sqs');
Queue::forward('updates', 'notifications');

Per inoltrare più code insieme, passa un array.

Queue::forward([
    'reports' => 'reports.fifo',
    'emails' => 'emails.fifo',
], connection: 'sqs');

Se il job specifica esplicitamente una connessione, quella indicazione ha la precedenza sulla configurazione di inoltro.

Esecuzione sincrona (test/sviluppo)

SendWelcomeEmail::dispatchSync($user);

Dispatch in bulk

Per molti job indipendenti senza tracciamento come nei batch:

use App\Jobs\ProcessUser;
use Illuminate\Support\Facades\Bus;

Bus::bulk(
    $users->map(fn ($user) => new ProcessUser($user))
);

Bus::bulk() invia in modo efficiente ma senza le funzionalità di batch (progresso, callback).

Catene di job

Concatenando i job puoi eseguire più job in sequenza. Se un job della catena fallisce, i job successivi non vengono eseguiti.

use App\Jobs\OptimizePodcast;
use App\Jobs\ProcessPodcast;
use App\Jobs\ReleasePodcast;
use Illuminate\Support\Facades\Bus;

Bus::chain([
    new ProcessPodcast($podcast),
    new OptimizePodcast($podcast),
    new ReleasePodcast($podcast),
])->dispatch();

Puoi anche aggiungere callback da eseguire quando l’intera catena è completata o quando un job della catena fallisce.

Bus::chain([
    new ProcessPodcast($podcast),
    new ReleasePodcast($podcast),
])->catch(function (Throwable $e) {
    // Gestione del fallimento di un job della catena
})->dispatch();

Batch di job

I batch permettono di dispatchare più job insieme e tracciarne il progresso complessivo. Per prima cosa crea la migration per la tabella job_batches.

php artisan make:batches-table
php artisan migrate

Usa il trait Batchable nella classe del job.

<?php

namespace App\Jobs;

use Illuminate\Bus\Batchable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class ImportContacts implements ShouldQueue
{
    use Batchable, Queueable;

    public function handle(): void
    {
        if ($this->batch()->cancelled()) {
            return;
        }

        // Importa il chunk di contatti...
    }
}

Con Bus::batch() puoi dispatchare il batch e registrare callback per completamento, fallimento e fine dell’esecuzione.

use App\Jobs\ImportContacts;
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;
use Throwable;

$batch = Bus::batch([
    new ImportContacts($chunkA),
    new ImportContacts($chunkB),
    new ImportContacts($chunkC),
])->then(function (Batch $batch) {
    // Tutti i job sono stati completati con successo
})->catch(function (Batch $batch, Throwable $e) {
    // Un job è fallito
})->finally(function (Batch $batch) {
    // L'esecuzione del batch è terminata
})->dispatch();

Puoi verificare lo stato del batch usando il suo ID.

$batch = Bus::findBatch($batchId);

$batch->totalJobs;      // numero totale di job
$batch->pendingJobs;    // numero di job in attesa
$batch->failedJobs;     // numero di job falliti
$batch->progress();     // percentuale di avanzamento (0-100)

Elaborazione dei job

queue:work

php artisan queue:work

Con driver/coda specifici:

php artisan queue:work redis --queue=emails
php artisan queue:work database

queue:work resta in esecuzione. Riavvia con queue:restart dopo modifiche. In produzione usa Supervisor.

Opzioni del worker

php artisan queue:work --tries=3 --timeout=60 --sleep=3

Opzione	Descrizione
`--tries=N`	Tentativi max prima del fallimento
`--timeout=N`	Secondi max per job
`--sleep=N`	Attesa quando la coda è vuota (default 3)
`--max-jobs=N`	Termina dopo N job
`--max-time=N`	Termina dopo N secondi
`--queue=A,B`	Priorità di code (A prima)

Impostazioni nella classe

use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;

#[Tries(3)]
#[Timeout(60)]
class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;
}

Contare i crash come eccezioni

Per impostazione predefinita, i tentativi che terminano perché il processo worker va in crash o viene terminato forzatamente, ad esempio per memoria insufficiente, non vengono conteggiati nel numero massimo di eccezioni del job (MaxExceptions). Se vuoi che anche questi tentativi vengano conteggiati come eccezioni, aggiungi l’attributo CountCrashesAsExceptions alla classe del job.

use Illuminate\Queue\Attributes\CountCrashesAsExceptions;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[MaxExceptions(3)]
#[CountCrashesAsExceptions]
class ProcessPodcast implements ShouldQueue
{
    // ...
}

Con questo attributo, il worker salva un marcatore nella cache dell’applicazione mentre elabora il job. Se al tentativo successivo il marcatore è ancora presente, il tentativo precedente viene conteggiato come eccezione.

Controllo dell’esecuzione con i middleware dei job

I middleware dei job permettono di isolare logiche trasversali, come la limitazione della frequenza o la prevenzione di esecuzioni concorrenti, dal metodo handle(), dichiarandole in modo esplicito nel metodo middleware(). Poiché la logica non viene scritta all’interno del job, lo stesso controllo può essere riutilizzato facilmente in più job.

/**
 * Restituisce i middleware attraversati dal job
 */
public function middleware(): array
{
    return [new RateLimited('backups')];
}

Puoi generare middleware personalizzati con il comando Artisan make:job-middleware. I middleware dei job possono essere applicati anche ai listener di eventi in coda, ai mailable e alle notifiche.

Limitazione della frequenza (RateLimited)

Definisci una limitazione tramite il metodo for della facade RateLimiter e applica il middleware Illuminate\Queue\Middleware\RateLimited al job.

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

// Definito in AppServiceProvider::boot()
RateLimiter::for('backups', function (object $job) {
    return $job->user->vipCustomer()
        ? Limit::none()
        : Limit::perHour(1)->by($job->user->id);
});

use Illuminate\Queue\Middleware\RateLimited;

public function middleware(): array
{
    return [new RateLimited('backups')];
}

I job che superano il limite vengono rilasciati automaticamente nella coda in base al tempo residuo della limitazione. Con releaseAfter() puoi fissare i secondi prima del nuovo tentativo, oppure con dontRelease() far terminare il job senza rimetterlo in coda.

public function middleware(): array
{
    return [(new RateLimited('backups'))->releaseAfter(60)];
    // Oppure, se non vuoi ritentare
    // return [(new RateLimited('backups'))->dontRelease()];
}

Anche i job rilasciati incrementano il contatore dei tentativi (attempts). Configura opportunamente #[Tries] o retryUntil().

Se usi Redis puoi ricorrere a Illuminate\Queue\Middleware\RateLimitedWithRedis, che offre prestazioni migliori.

use Illuminate\Queue\Middleware\RateLimitedWithRedis;

public function middleware(): array
{
    return [new RateLimitedWithRedis('backups')];
}

Prevenzione delle esecuzioni concorrenti (WithoutOverlapping)

Illuminate\Queue\Middleware\WithoutOverlapping impedisce che più istanze dello stesso job vengano eseguite contemporaneamente sulla base di una chiave arbitraria. È utile quando vuoi aggiornare una determinata risorsa un elemento alla volta.

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function middleware(): array
{
    // Evita che i job di aggiornamento del punteggio di credito dello stesso utente si sovrappongano
    return [new WithoutOverlapping($this->user->id)];
}

I job duplicati vengono rilasciati in coda; con releaseAfter() puoi indicare l’intervallo prima del nuovo tentativo, mentre con dontRelease() puoi eliminarli subito. Poiché il lock si basa sul meccanismo dei lock atomici, è consigliabile specificare esplicitamente la scadenza con expireAfter(), così il lock non resta bloccato in caso di errore o timeout imprevisto del job.

public function middleware(): array
{
    return [
        (new WithoutOverlapping($this->order->id))
            ->releaseAfter(60)
            ->expireAfter(180),
    ];
}

Per impostazione predefinita la prevenzione dei duplicati avviene solo all’interno della stessa classe job. Se vuoi condividere la chiave di lock tra classi job differenti, usa il metodo shared().

Contenimento delle eccezioni consecutive (ThrottlesExceptions)

Illuminate\Queue\Middleware\ThrottlesExceptions è pensato per i job che interagiscono con servizi instabili, come API esterne: quando si verificano un certo numero di eccezioni, sospende temporaneamente le esecuzioni successive. Si usa tipicamente in combinazione con un limite di tentativi basato sul tempo (retryUntil()).

use DateTime;
use Illuminate\Queue\Middleware\ThrottlesExceptions;

public function middleware(): array
{
    // Se si verificano 10 eccezioni consecutive, ferma l'esecuzione del job per 5 minuti
    return [new ThrottlesExceptions(10, 5 * 60)];
}

public function retryUntil(): DateTime
{
    return now()->addMinutes(30);
}

Con when() puoi limitare il throttling a specifiche eccezioni, oppure con deleteWhen() puoi eliminare il job quando si verifica una certa eccezione, ottenendo un controllo più preciso.

use App\Exceptions\CustomerDeletedException;
use Illuminate\Http\Client\HttpClientException;
use Illuminate\Queue\Middleware\ThrottlesExceptions;

public function middleware(): array
{
    return [
        (new ThrottlesExceptions(10, 10 * 60))
            ->when(fn ($e) => $e instanceof HttpClientException)
            ->deleteWhen(CustomerDeletedException::class),
    ];
}

Se usi Redis, Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis permette di gestire il throttling in modo più efficiente.

Rilascio del job (middleware Release)

Per rimettere il job in coda al soddisfacimento di una condizione.

use Illuminate\Queue\Middleware\Release;

public function middleware(): array
{
    return [
        Release::when($this->order->isPending(), releaseAfter: 60),
    ];
}

Release::unless() rilascia quando la condizione è false.

return [
    Release::unless($this->order->isPaid(), releaseAfter: 60),
];

Con closure:

return [
    Release::when(function (): bool {
        return ! $this->order->isPaid();
    }, releaseAfter: 60),
];

Rilasciare incrementa il contatore dei tentativi. Configura correttamente #[Tries] o $tries.

Gestione dei job falliti

Tabella failed_jobs

php artisan make:queue-failed-table
php artisan migrate

Cleanup al fallimento

use Throwable;

public function failed(?Throwable $exception): void
{
    // Notifica ad admin, ecc.
}

Interrompere il retry per certe eccezioni

In withExceptions() di bootstrap/app.php:

use App\Exceptions\InvalidPodcastSourceException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetry([
        InvalidPodcastSourceException::class,
    ]);
})

Con closure:

use App\Exceptions\PodcastProcessingException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetryWhen(function (PodcastProcessingException $e) {
        return $e->reason() === 'Subscription expired';
    });
})

Per eccezioni deterministiche (validazione, sottoscrizione scaduta) è efficiente fallire subito.

Elenco job falliti

php artisan queue:failed

Retry

php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece
php artisan queue:retry all

Eliminazione

php artisan queue:forget ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece
php artisan queue:flush

Driver più usati

database

Semplice, senza middleware aggiuntivi. Salva su jobs e i worker fanno polling.

Pro: setup semplice, riusa RDBMS
Contro: carico DB, non adatto a grandi volumi

QUEUE_CONNECTION=database

redis

Il più usato in produzione. In memoria, alta throughput.

Pro: veloce, scalabile
Contro: richiede server Redis

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

In produzione considera Laravel Horizon per monitorare in tempo reale.

Esercizio in produzione con Supervisor

In produzione serve un supervisor che riavvii queue:work se cade.

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/worker.log
stopwaitsecs=3600

numprocs=2 per due worker in parallelo.

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Esempio pratico: invio email in coda

Crea il job

php artisan make:job SendOrderConfirmation

Implementa

<?php

namespace App\Jobs;

use App\Models\Order;
use App\Mail\OrderConfirmed;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Support\Facades\Mail;

#[Tries(3)]
#[Timeout(30)]
class SendOrderConfirmation implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public Order $order,
    ) {}

    public function handle(): void
    {
        Mail::to($this->order->user->email)
            ->send(new OrderConfirmed($this->order));
    }
}

Dispatch dal controller

use App\Jobs\SendOrderConfirmation;

public function store(Request $request): RedirectResponse
{
    $order = Order::create($request->validated());

    SendOrderConfirmation::dispatch($order);

    return redirect()->route('orders.show', $order)
        ->with('success', 'Ordine ricevuto.');
}

Avvia il worker

php artisan queue:work --tries=3 --timeout=30

Riepilogo

Quando usare le code

Invio email/SMS
Elaborazione immagini/video
Chiamate ad API esterne
Generazione report o export CSV
Invio webhook

Suggerimenti in sviluppo

Con QUEUE_CONNECTION=sync i job vengono eseguiti subito senza worker.

QUEUE_CONNECTION=sync

Comandi comuni

php artisan queue:work
php artisan queue:restart
php artisan queue:failed
php artisan queue:retry all
php artisan queue:flush

​Cosa sono le code

​Configurazione delle code

​config/queue.php

​.env

​Preparazione del driver database

​Preparazione del driver Redis

​SQS Overflow Storage

​Creazione della classe job

​make:job

​Struttura del job

​Dispatch del job

​dispatch()

​Ritardato

​dispatchAfterResponse()

​Coda specifica

​Queue Routing

​Inoltro delle code (Queue::forward())

​Esecuzione sincrona (test/sviluppo)

​Dispatch in bulk

​Catene di job

​Batch di job

​Elaborazione dei job

​queue:work

​Opzioni del worker

​Impostazioni nella classe

​Contare i crash come eccezioni

​Controllo dell’esecuzione con i middleware dei job

​Limitazione della frequenza (RateLimited)

​Prevenzione delle esecuzioni concorrenti (WithoutOverlapping)

​Contenimento delle eccezioni consecutive (ThrottlesExceptions)

​Rilascio del job (middleware Release)

​Gestione dei job falliti

​Tabella failed_jobs

​Cleanup al fallimento

​Interrompere il retry per certe eccezioni

​Elenco job falliti

​Retry

​Eliminazione

​Driver più usati

​database

​redis

​Esercizio in produzione con Supervisor

​Esempio pratico: invio email in coda

​Riepilogo

Cosa sono le code

Configurazione delle code

config/queue.php

.env

Preparazione del driver database

Preparazione del driver Redis

SQS Overflow Storage

Creazione della classe job

make:job

Struttura del job

Dispatch del job

dispatch()

Ritardato

dispatchAfterResponse()

Coda specifica

Queue Routing

Inoltro delle code (`Queue::forward()`)

Esecuzione sincrona (test/sviluppo)

Dispatch in bulk

Catene di job

Batch di job

Elaborazione dei job

queue:work

Opzioni del worker

Impostazioni nella classe

Contare i crash come eccezioni

Controllo dell’esecuzione con i middleware dei job

Limitazione della frequenza (RateLimited)

Prevenzione delle esecuzioni concorrenti (WithoutOverlapping)

Contenimento delle eccezioni consecutive (ThrottlesExceptions)

Rilascio del job (middleware Release)

Gestione dei job falliti

Tabella failed_jobs

Cleanup al fallimento

Interrompere il retry per certe eccezioni

Elenco job falliti

Retry

Eliminazione

Driver più usati

database

redis

Esercizio in produzione con Supervisor

Esempio pratico: invio email in coda

Riepilogo