Laravel Queueable Action

https://github.com/spatie/laravel-queueable-action
Admin
Laravel Queueable Action is a package that adds easy support for making Laravel actions queueable,...
Tokens:6,202
Snippets:48
Trust Score:10
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Package Installation and Configuration

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Commands to install the package via Composer and publish the configuration file, along with the default configuration structure.

```bash
composer require spatie/laravel-queueable-action
php artisan vendor:publish --provider="Spatie\QueueableAction\QueueableActionServiceProvider" --tag="config"
```

```php
return [
    'job_class' => \Spatie\QueueableAction\ActionJob::class,
];
```

--------------------------------

### Install and Configure Laravel Queueable Action

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Instructions for installing the package via Composer and publishing the configuration file to customize the underlying job class.

```bash
composer require spatie/laravel-queueable-action
php artisan vendor:publish --provider="Spatie\QueueableAction\QueueableActionServiceProvider" --tag="config"
```

```php
// config/queuableaction.php
return [
    'job_class' => \Spatie\QueueableAction\ActionJob::class,
];
```

--------------------------------

### Complete Action Example with All Features in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates a comprehensive Laravel Queueable Action class, showcasing queue configuration, dependency injection, middleware, backoff strategies, retryUntil, tags, and failure handling. It includes an example of how to dispatch this action from a controller, including chaining other jobs.

```php
<?php

namespace App\Actions;

use App\Models\Order;
use App\Services\PaymentGateway;
use App\Services\InventoryService;
use App\Notifications\OrderFailed;
use DateTime;
use Illuminate\Queue\Middleware\RateLimited;
use Illuminate\Queue\Middleware\WithoutOverlapping;
use Spatie\QueueableAction\QueueableAction;
use Throwable;
use Illuminate\Support\Facades\Log;
use App\Http\Controllers\Controller;
use App\Http\Requests\OrderRequest;
use Spatie\QueueableAction\ActionJob;

class ProcessOrderComplete
{
    use QueueableAction;

    // Queue configuration properties
    public string $connection = 'redis';
    public string $queue = 'orders';
    public int $tries = 5;
    public int $timeout = 60;
    public int $maxExceptions = 3;

    // Injected dependencies
    protected PaymentGateway $paymentGateway;
    protected InventoryService $inventory;
    protected ?Order $order = null;

    public function __construct(
        PaymentGateway $paymentGateway,
        InventoryService $inventory
    ) {
        $this->paymentGateway = $paymentGateway;
        $this->inventory = $inventory;
    }

    public function execute(Order $order): void
    {
        $this->order = $order;

        // Process payment
        $this->paymentGateway->charge(
            $order->customer,
            $order->total_amount
        );

        // Update inventory
        foreach ($order->items as $item) {
            $this->inventory->decrement($item->product_id, $item->quantity);
        }

        // Mark order as complete
        $order->update([
            'status' => 'completed',
            'processed_at' => now(),
        ]);
    }

    public function middleware(): array
    {
        return [
            new RateLimited('orders'),
            (new WithoutOverlapping($this->order?->id ?? 'default'))
                ->expireAfter(60),
        ];
    }

    public function backoff(): array
    {
        return [5, 15, 30, 60, 120]; // Exponential backoff
    }

    public function retryUntil(): DateTime
    {
        return now()->addHours(2);
    }

    public function tags(): array
    {
        return [
            'order-processing',
            'order:' . ($this->order?->id ?? 'unknown'),
            'customer:' . ($this->order?->customer_id ?? 'unknown'),
        ];
    }

    public function failed(Throwable $exception): void
    {
        if ($this->order) {
            $this->order->update(['status' => 'failed']);
            $this->order->customer->notify(
                new OrderFailed($this->order, $exception->getMessage())
            );
        }

        Log::error('Order processing failed', [
            'order_id' => $this->order?->id,
            'exception' => $exception->getMessage(),
            'trace' => $exception->getTraceAsString(),
        ]);
    }
}

// Usage in a controller
class OrderController extends Controller
{
    public function store(
        OrderRequest $request,
        ProcessOrderComplete $processOrder
    ) {
        $order = Order::create($request->validated());

        // Queue the action with chaining
        $processOrder
            ->onQueue('high-priority') // Override default queue
            ->execute($order)
            ->chain([
                new ActionJob(SendOrderConfirmation::class, [$order]),
                new ActionJob(NotifyWarehouse::class, [$order]),
            ]);

        return response()->json([
            'message' => 'Order received and processing',
            'order' => $order,
        ], 202);
    }
}

```

--------------------------------

### Batching Queueable Actions with Laravel Bus in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Shows how to dispatch multiple queueable actions in parallel using Laravel's Bus facade for batch processing. This is useful for handling large numbers of independent tasks efficiently. It includes examples of handling batch success, failure, and completion. Dependencies include AppActionsProcessImage and AppActionsGenerateThumbnail.

```php
<?php

use App\Actions\ProcessImage;
use App\Actions\GenerateThumbnail;
use Illuminate\Support\Facades\Bus;
use Spatie\QueueableAction\ActionJob;

$images = Image::whereNull('processed_at')->get();

// Dispatch actions as a batch
Bus::batch(
    $images->map(fn ($image) => new ActionJob(ProcessImage::class, [$image]))
)->then(function ($batch) {
    // All jobs completed successfully
    Log::info("Processed {$batch->totalJobs} images");
})->catch(function ($batch, $e) {
    // First batch job failure detected
    Log::error("Image processing failed: {$e->getMessage()}");
})->finally(function ($batch) {
    // Batch has finished executing
    Notification::send($admin, new BatchCompleted($batch));
})->dispatch();

// Batch multiple different actions together
Bus::batch([
    new ActionJob(ProcessImage::class, [$image1]),
    new ActionJob(GenerateThumbnail::class, [$image1, 'small']),
    new ActionJob(GenerateThumbnail::class, [$image1, 'medium']),
])->dispatch();

```

--------------------------------

### Run Package Tests

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Execute the package test suite using Composer.

```bash
composer test
```

--------------------------------

### Defining and Using Queueable Actions

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Shows how to create an action class using the QueueableAction trait and how to trigger it from a controller either synchronously or asynchronously.

```php
class MyAction
{
    use QueueableAction;

    public function __construct(OtherAction $otherAction, ServiceFromTheContainer $service) {
        $this->otherAction = $otherAction;
        $this->service = $service;
    }

    public function execute(MyModel $model, RequestData $requestData) {
        // Logic here
    }
}

class MyController
{
    public function store(MyRequest $request, MyModel $model, MyAction $action) {
        $requestData = RequestData::fromRequest($myRequest);
        $action->onQueue()->execute($model, $requestData);
        $action->execute($model, $requestData);
    }
}
```

--------------------------------

### Executing Queueable Actions

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Demonstrates how to execute an action on the default queue or a specific named queue using the onQueue method.

```php
$myAction->onQueue()->execute();
$myAction->onQueue('my-favorite-queue')->execute();
```

--------------------------------

### Generate Action Classes via Artisan

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Use the Artisan command-line interface to scaffold new action classes, with options for queueable or synchronous execution.

```bash
# Create a queueable action class
php artisan make:action SendWelcomeEmail

# Create a synchronous action class
php artisan make:action ProcessPayment --sync
```

--------------------------------

### Invokable Queueable Actions

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Demonstrates how to implement queueable actions using the __invoke method, which is automatically detected by the package.

```php
class MyInvokeableAction
{
    use QueueableAction;

    public function __invoke(MyModel $model, RequestData $requestData) {
        // Logic here
    }
}

$myInvokeableAction->onQueue()->execute($model, $requestData);
```

--------------------------------

### Using __invoke() Method for Queueable Actions in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates how to use PHP's magic __invoke() method as an alternative to the execute() method for Queueable Actions. The package automatically detects and uses __invoke() if present. Dependencies include AppModelsProduct and AppServicesInventoryService. It takes a Product model and an integer quantity as input.

```php
<?php

namespace App\Actions;

use App\Models\Product;
use App\Services\InventoryService;
use Spatie\QueueableAction\QueueableAction;

class UpdateInventory
{
    use QueueableAction;

    protected InventoryService $inventory;

    public function __construct(InventoryService $inventory)
    {
        $this->inventory = $inventory;
    }

    public function __invoke(Product $product, int $quantity)
    {
        $this->inventory->adjust($product->id, $quantity);
        $product->update(['stock' => $product->stock + $quantity]);
    }
}

// Usage - still use execute() to dispatch, even with __invoke()
$action = app(UpdateInventory::class);
$action->onQueue()->execute($product, 50);

```

--------------------------------

### Chaining Queueable Actions with ActionJob in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Illustrates how to chain multiple queueable actions sequentially using the ActionJob class. ActionJob accepts an action class or instance and an array of parameters. This allows for complex workflows where actions depend on the output or completion of previous actions. Dependencies include various AppActions classes.

```php
<?php

use App\Actions\ProcessOrder;
use App\Actions\SendOrderConfirmation;
use App\Actions\UpdateInventory;
use App\Actions\NotifyWarehouse;
use Spatie\QueueableAction\ActionJob;

$order = Order::find(1);

// Chain multiple actions that execute sequentially
app(ProcessOrder::class)
    ->onQueue()
    ->execute($order)
    ->chain([
        // ActionJob accepts the action class and an array of parameters
        new ActionJob(SendOrderConfirmation::class, [$order]),
        new ActionJob(UpdateInventory::class, [$order->product, -$order->quantity]),
        new ActionJob(NotifyWarehouse::class, [$order]),
    ]);

// Chain with shared arguments across actions
$args = [$order->id, $order->customer_id];

app(ProcessOrder::class)
    ->onQueue()
    ->execute($order)
    ->chain([
        new ActionJob(SendOrderConfirmation::class, $args),
        new ActionJob(UpdateInventory::class, $args),
    ]);

```

--------------------------------

### Implement Custom ActionJob Class

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates how to extend the base ActionJob class to add custom middleware, tags, or properties, and register it via the configuration file.

```php
class CustomActionJob extends ActionJob {
    public function middleware(): array {
        return [new \Illuminate\Queue\Middleware\WithoutOverlapping($this->actionClass)];
    }
}

// config/queuableaction.php
return ['job_class' => \App\Jobs\CustomActionJob::class];
```

--------------------------------

### Implement Queueable Action with Dependency Injection

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates how to use the QueueableAction trait to create an action that supports dependency injection and can be executed either synchronously or asynchronously.

```php
<?php

namespace App\Actions;

use App\Models\User;
use App\Services\EmailService;
use Spatie\QueueableAction\QueueableAction;

class SendWelcomeEmail
{
    use QueueableAction;

    protected EmailService $emailService;

    public function __construct(EmailService $emailService)
    {
        $this->emailService = $emailService;
    }

    public function execute(User $user, string $subject = 'Welcome!')
    {
        $this->emailService->send($user->email, $subject, 'emails.welcome', [
            'name' => $user->name,
        ]);
    }
}

// Usage in a controller
class UserController
{
    public function store(Request $request, SendWelcomeEmail $action)
    {
        $user = User::create($request->validated());
        $action->onQueue()->execute($user, 'Welcome to our platform!');
        $action->execute($user, 'Welcome to our platform!');
        return response()->json(['user' => $user]);
    }
}
```

--------------------------------

### Testing Queueable Actions with PHPUnit

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates various testing assertions for queued actions, including checking for successful pushes, execution counts, and job chaining. These tests require the Laravel Queue facade to be faked before execution.

```php
<?php

namespace TestsFeature;

use AppActionsSendWelcomeEmail;
use AppActionsProcessOrder;
use AppActionsNotifyWarehouse;
use IlluminateSupportFacadesQueue;
use SpatieQueueableActionActionJob;
use SpatieQueueableActionTestingQueueableActionFake;
use TestsTestCase;

class OrderTest extends TestCase
{
    public function test_order_queues_welcome_email(): void
    {
        Queue::fake();

        $user = User::factory()->create();
        $action = app(SendWelcomeEmail::class);

        $action->onQueue()->execute($user);

        // Assert the action was pushed to the queue
        QueueableActionFake::assertPushed(SendWelcomeEmail::class);
    }

    public function test_action_queued_multiple_times(): void
    {
        Queue::fake();

        $action = app(SendWelcomeEmail::class);

        $action->onQueue()->execute($user1);
        $action->onQueue()->execute($user2);
        $action->onQueue()->execute($user3);

        // Assert the action was pushed exactly 3 times
        QueueableActionFake::assertPushedTimes(SendWelcomeEmail::class, 3);
    }

    public function test_action_not_queued_on_validation_failure(): void
    {
        Queue::fake();

        // Simulate validation failure scenario
        $this->postJson('/orders', ['invalid' => 'data']);

        // Assert the action was NOT pushed
        QueueableActionFake::assertNotPushed(ProcessOrder::class);
    }

    public function test_action_queued_with_chain(): void
    {
        Queue::fake();

        $order = Order::factory()->create();

        app(ProcessOrder::class)
            ->onQueue()
            ->execute($order)
            ->chain([
                new ActionJob(NotifyWarehouse::class, [$order]),
                new ActionJob(SendWelcomeEmail::class, [$order->user]),
            ]);

        // Assert the action was pushed with the expected chain
        QueueableActionFake::assertPushedWithChain(
            ProcessOrder::class,
            [NotifyWarehouse::class, SendWelcomeEmail::class]
        );
    }

    public function test_action_queued_without_chain(): void
    {
        Queue::fake();

        app(ProcessOrder::class)->onQueue()->execute($order);

        // Assert the action was pushed without any chained jobs
        QueueableActionFake::assertPushedWithoutChain(ProcessOrder::class);
    }
}
```

--------------------------------

### Configure Backoff Strategies for Queueable Actions

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates how to define fixed, exponential, or dynamic backoff intervals for retrying failed queueable actions using properties or methods.

```php
class ProcessPayment {
    use QueueableAction;
    public int $backoff = 5;
    public function execute(Order $order) { ... }
}

class ProcessPaymentWithExponentialBackoff {
    use QueueableAction;
    public function backoff(): array {
        return [1, 5, 10];
    }
}

class ProcessPaymentWithDynamicBackoff {
    use QueueableAction;
    public function backoff(): int {
        return min($this->attemptCount * 2, 30);
    }
}
```

--------------------------------

### Configure Queue Names for Actions

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Shows how to define a default queue for an action class using a property or override it dynamically during execution.

```php
<?php

namespace App\Actions;

use App\Models\Order;
use Spatie\QueueableAction\QueueableAction;

class ProcessOrder
{
    use QueueableAction;

    public string $queue = 'orders';

    public function execute(Order $order)
    {
        $order->process();
        $order->update(['status' => 'processed']);
    }
}

$action = app(ProcessOrder::class);
$action->onQueue()->execute($order);
$action->onQueue('high-priority')->execute($order);
$action->execute($order);
```

--------------------------------

### Configure Queue Properties

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Illustrates how to set standard Laravel queue properties like connection, queue name, tries, and timeouts directly within the action class.

```php
class HeavyDataProcessing {
    use QueueableAction;
    public string $connection = 'redis';
    public string $queue = 'heavy-processing';
    public int $tries = 3;
    public int $timeout = 120;
}
```

--------------------------------

### Applying Job Middleware to Queueable Actions in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Demonstrates how to apply Laravel job middleware, such as rate limiting and preventing overlaps, to Queueable Actions by overriding the `middleware()` method. This is crucial for managing resource usage and preventing race conditions. Dependencies include AppModelsUser, RateLimited, and WithoutOverlapping middleware.

```php
<?php

namespace App\Actions;

use App\Models\User;
use Illuminate\Queue\Middleware\RateLimited;
use Illuminate\Queue\Middleware\WithoutOverlapping;
use Spatie\QueueableAction\QueueableAction;

class SendNotification
{
    use QueueableAction;

    public function execute(User $user, string $message)
    {
        $user->notify(new GenericNotification($message));
    }

    public function middleware(): array
    {
        return [
            new RateLimited('notifications'),
            new WithoutOverlapping('user-notification'),
        ];
    }
}

// Configure the rate limiter in AppServiceProvider
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('notifications', function ($job) {
    return Limit::perMinute(10);
});

// Usage
$action = app(SendNotification::class);
$action->onQueue()->execute($user, 'Your order has shipped!');

```

--------------------------------

### Set Retry Deadline with retryUntil

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Shows how to implement the retryUntil method to define a specific timestamp or duration after which an action should stop attempting retries.

```php
class SendTimeSensitiveAlert {
    use QueueableAction;
    public int $tries = 10;
    public function retryUntil(): DateTime {
        return now()->addMinutes(30);
    }
}
```

--------------------------------

### QueueableActionFake Assertion Methods

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

A list of available assertion methods provided by QueueableActionFake to verify queue interactions in tests.

```php
QueueableActionFake::assertPushed(string $actionClass);
QueueableActionFake::assertPushedTimes(string $actionClass, int $times = 1);
QueueableActionFake::assertNotPushed(string $actionClass);
QueueableActionFake::assertPushedWithChain(string $actionClass, array $expextedActionChain = [])
QueueableActionFake::assertPushedWithoutChain(string $actionClass)
```

--------------------------------

### Handle Failed Jobs with failed()

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Explains how to define a failed method to execute custom logic, such as logging or notifications, when an action exhausts all retry attempts.

```php
public function failed(Throwable $exception): void {
    Log::error('Order processing failed', ['error' => $exception->getMessage()]);
    $this->order->update(['status' => 'failed']);
}
```

--------------------------------

### Customizing Laravel Horizon Tags for Queueable Actions in PHP

Source: https://context7.com/spatie/laravel-queueable-action/llms.txt

Explains how to override the `tags()` method within a Queueable Action to provide custom tags for monitoring and filtering jobs in Laravel Horizon. This allows for better organization and identification of specific action types or related data. Dependencies include AppModelsUser and SpatieQueueableActionQueueableAction.

```php
<?php

namespace App\Actions;

use App\Models\User;
use Spatie\QueueableAction\QueueableAction;

class SyncUserData
{
    use QueueableAction;

    protected ?User $user = null;

    public function execute(User $user)
    {
        $this->user = $user;
        // Sync user data with external service
    }

    public function tags(): array
    {
        return [
            'sync',
            'user-data',
            'user:' . ($this->user?->id ?? 'unknown'),
        ];
    }
}

// In Horizon, jobs will be tagged with: ['sync', 'user-data', 'user:123']
$action = app(SyncUserData::class);
$action->onQueue()->execute($user);

```

--------------------------------

### Customize Action Tags and Middleware

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Override the tags() or middleware() methods within your action class to customize Horizon tags or apply job middleware.

```php
class CustomTagsAction
{
    use QueueableAction;

    public function tags() {
        return ['action', 'custom_tags'];
    }

    public function middleware() {
        return [new RateLimited()];
    }
}
```

--------------------------------

### Test Queueable Actions with PHPUnit

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Use the QueueableActionFake class to assert that specific actions were pushed to the queue. Ensure Queue::fake() is called before performing assertions.

```php
/** @test */
public function it_queues_an_action()
{
    Queue::fake();

    (new DoSomethingAction)->onQueue()->execute();

    QueueableActionFake::assertPushed(DoSomethingAction::class);
}
```

--------------------------------

### Chain Queueable Actions

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Chain multiple actions together by wrapping them in an ActionJob. This allows sequential execution of queued tasks.

```php
use Spatie\QueueableAction\ActionJob;

$args = [$userId, $data];

app(MyAction::class)
    ->onQueue()
    ->execute(...$args)
    ->chain([
        new ActionJob(AnotherAction::class, $args),
    ]);
```

--------------------------------

### Configure Action Backoff

Source: https://github.com/spatie/laravel-queueable-action/blob/main/README.md

Define retry backoff strategies by setting a $backoff property or a backoff() method. Supports integer values or arrays for exponential backoff.

```php
class BackoffAction
{
    use QueueableAction;
    
    public $backoff = 3;

    public function backoff(): array
    {
        return [1, 5, 10];
    }
}
```
Tokens:
Raw