Getting Started

Release 7.3.0 is additive: no breaking changes are called out. Existing operation dispatch code should keep working, but queued-operation behavior is now more configurable.

Minimal steps:

Upgrade with Composer and run your test suite:
```
composer update
php artisan test
```
Publish/check the package config if you have not already:
```
php artisan vendor:publish --tag=config
```
Look first at the package’s queue section, especially queue.job and the new uniqueness-lock duration setting.
Confirm your queue connection and worker are configured as usual:
```
php artisan queue:work --queue=default
```
Start with one existing synchronous or inline operation that is safe to move to the queue, such as report generation, webhook delivery, or post-registration provisioning:
```
GenerateReport::dispatch($user)->onQueue('reports');
```

First use case: dispatch an operation as a queued job and use the new uniqueness lock duration to prevent duplicate queued work for the same logical operation.

Implementation Patterns

Queue an operation with explicit queue placement

Use the package’s dispatch API as normal, then place slower operations on dedicated queues:

GenerateReport::dispatch($user)
    ->onQueue('reports');

Run a worker for that queue:

php artisan queue:work --queue=reports

This keeps latency-sensitive HTTP requests fast while preserving the package’s operation conventions.

Tune uniqueness locking for queued operations

The new configurable uniqueness lock duration is useful when the same operation can be dispatched more than once, e.g. double-clicks, retries, or overlapping scheduled jobs.

Set the lock duration in the package queue config to a value that is:

Longer than the expected maximum runtime of the operation.
Shorter than the window in which stale duplicates would be harmful.
Consistent with your queue retry and timeout settings.

Make sure the operation’s uniqueness key includes the right identifiers, such as user ID, tenant ID, and report type. Avoid a global lock unless you truly want one operation across the whole application.

Override the dispatched job class

Use queue.job when you need custom job behavior without forking the package:

// config/<package>.php
'queue' => [
    'job' => App\Jobs\Operations\PackageOperationJob::class,
],

Your custom job should preserve the package’s expected constructor/contract and extend or mimic the default job. Common reasons to override:

Add job middleware.
Set custom $tries, $timeout, $backoff, or retryUntil().
Add Horizon tags.
Integrate tracing, logging, or tenant context.
Customize failed-job handling.

Example:

namespace App\Jobs\Operations;

use Vendor\Package\Jobs\OperationJob;

class PackageOperationJob extends OperationJob
{
    public $tries = 5;

    public $timeout = 120;

    public function backoff(): array
    {
        return [10, 30, 60];
    }

    public function middleware(): array
    {
        return [
            new \Illuminate\Queue\Middleware\WithoutOverlapping($this->operationKey()),
        ];
    }
}

Keep the parent job’s constructor signature intact unless you also control every dispatch path.

Use `--isolated` from CLI wrappers

The --isolated fix aligns the package with Laravel core presence semantics. If you have an Artisan command that dispatches an operation, treat --isolated as a flag:

php artisan operations:run generate-report --isolated

Do not require --isolated=1; the option should now be detected when present in the same way Laravel core options are detected.

Test with fakes and the sync driver

For fast tests:

Queue::fake();

GenerateReport::dispatch($user);

Queue::assertPushed(GenerateReportJob::class);

For integration tests, use the sync queue driver but set short lock durations so uniqueness state does not leak between tests. Clear the cache store used by the package between tests if uniqueness is cache-backed.

Gotchas and Tips

Run config:clear after config changes. If you use config:cache, changing queue.job or the uniqueness lock duration will not take effect until the config cache is rebuilt.
Uniqueness locks are not a mutex around side effects. They prevent duplicate queued work from being accepted for a period; they do not make the operation itself transactional. Use database constraints or idempotency keys for critical side effects.
Lock duration must fit your retry model. If the lock expires before a long-running job finishes, another job can be dispatched while the first is still running. If the lock is too long, legitimate retries may be blocked.
Custom job classes are an extension point, not a free pass. If you override queue.job, verify the package still receives the payload it expects. Run queued-operation tests against the custom job class.
Restart workers after deploying a job-class override. Queue workers hold code in memory:
```
php artisan queue:restart
```
Do not confuse --isolated with queue uniqueness. --isolated controls command-level presence/behavior; uniqueness locking controls duplicate queued operation dispatch. Use both deliberately, not interchangeably.
Watch failed jobs. For queued operations, use php artisan queue:failed, Horizon, or your monitoring tool. The new lock-duration setting can hide repeated dispatch attempts, so make sure failures are still visible through logs and failed-job records.
Prefer explicit queue names. If you use dedicated queues for operations, update worker and deployment configuration so those queues are actually processed.
Upgrade risk is low, but test custom configuration. The release is additive, but any app overriding job classes or relying on old --isolated parsing should add a focused regression test.

Laravel Actions Laravel Package