Queues

Introduction

The Maravel queue service provides a unified API across a variety of different queue back-ends. Queues allow you to defer the processing of a time-consuming task, such as performing a task on a remote server, until a later time, which drastically speeds up web requests to your application.

Like many other parts of the framework, Maravel’s queued jobs function almost identically to Maravelith’s queued jobs. To learn more about queuing jobs in Maravel, please review the full Maravelith queue documentation.

Note: Closure jobs are not supported by Maravel, but Storable Array Callables are fully supported and highly recommended.

Configuration

The queue configuration options are in the .env file.

If you would like to thoroughly customize the queue configuration, you must copy the entire vendor/macropay-solutions/maravel-framework/config/queue.php file to the config directory in the root of your project and adjust the necessary configuration options as needed. If the config directory does not exist, you should create it.

After creating the configuration file, ensure that the configuration file is loaded via your bootstrap/app.php file:

$app->configure('queue');

Driver Prerequisites

Database

In order to use the database queue driver, you will need database tables to hold the jobs and failures. You may execute the php artisan queue:table Artisan command to generate a migration for the jobs table, while the php artisan queue:failed-table command may be used to generate a migration for the failed-jobs table:

Schema::create('jobs', function (Blueprint $table) {
    $table->bigIncrements('id');
    $table->string('queue');
    $table->longText('payload');
    $table->tinyInteger('attempts')->unsigned();
    $table->unsignedInteger('reserved_at')->nullable();
    $table->unsignedInteger('available_at');
    $table->unsignedInteger('created_at');
    $table->index(['queue', 'reserved_at']);
});

Schema::create('failed_jobs', function (Blueprint $table) {
    $table->increments('id');
    $table->text('connection');
    $table->text('queue');
    $table->longText('payload');
    $table->longText('exception');
    $table->timestamp('failed_at')->useCurrent();
});

Redis

In order to use the Redis queue driver, you will need to install the illuminate/redis package via Composer. Then, you should register the Illuminate\Redis\RedisServiceProvider in your bootstrap/app.php file.

Other Queue Dependencies

The following dependencies are needed for the listed queue drivers:

• Amazon SQS: aws/aws-sdk-php ~3.0
• Beanstalkd: pda/pheanstalk ~3.0

Differences From Maravelith

As mentioned, Maravel’s queued jobs function identically to Maravelith’s queued jobs. However, there are a few minor differences regarding generation and dispatching.

Generators

Unlike legacy micro-frameworks, Maravel includes generator commands for automatically creating new Job classes, see Artisan. These generated classes automatically include the necessary InteractsWithQueue, Queueable, and SerializesModels traits, providing the basic structure shared by every Job class.

Dispatching Jobs

You should consult the full Maravelith queue documentation for complete information on dispatching queued jobs. Just like in the Maravelith framework, you may use the dispatch helper function to dispatch jobs from anywhere within your Maravel application:

dispatch(new ExampleJob);

Of course, you may also use the Queue facade. If you choose to use the facade, be sure to uncomment the call to $app->withFacades() in your bootstrap/app.php file:

Queue::push(new ExampleJob);

Warning: \Illuminate\Support\Facades\Queue::push should not be used in combination with the ShouldBeUnique interface. Furthermore, Queue::push should not be used for callable arrays!

Storable Array Callables & Strict Security

Maravel supports the same Storable Array Callables as Maravelith, offering a secure, high-performance alternative to traditional object-based jobs by eliminating serialization overhead. For a deep dive into chaining, batching, and error handling with array callables, please review the full Maravelith queue documentation.

dispatch([EmailService::class, 'sendWelcomeEmail', ['userId' => $user->id]]);

To completely eliminate the risk of PHP Object Injection (POI) vulnerabilities, you may instruct Maravel to aggressively reject any serialized objects pushed to the queue. You can enable this strict security boundary by overriding the FORBID_SERIALIZED_OBJECTS_IN_QUEUE constant in your application’s root Application class:

namespace App;

class Application extends \Laravel\Lumen\Application
{
    public const FORBID_SERIALIZED_OBJECTS_IN_QUEUE = true;
}

Warning: When strict mode is enabled, dispatch strictly forbids objects in payloads or chained arrays. Eloquent models are not automatically serialized and re-fetched natively; developers are responsible for passing primitive IDs and querying fresh database state inside their array callables. For detailed examples of allowed chaining formats, see the Storable Array Callables documentation.

SQS FIFO and Fair Queues

Maravel Framework supports Amazon SQS FIFO (First-In-First-Out) queues through message deduplication.

Example:

\dispatch(new JobExample($payload))->onGroup('customer-' . $payload['customer_id']);

To prevent duplicate dispatches within a 5-minute window, implement a deduplicationId method with a string return type in your job class. If this method is omitted, a default Str::orderedUuid()->toString() will be used, meaning duplicates will be processed:

/**
 * Get the job's deduplication ID.
 */
public function deduplicationId(): string
{
    return 'prefix-' . $this->customId;
}