# As job

# Methods provided

Lists all methods provided by the trait.

# dispatch

Dispatches a job asynchronously.

SendTeamReportEmail::dispatch($team);

# dispatchIf

Dispatches a job asynchronously if the condition is met.

SendTeamReportEmail::dispatchIf($team->plan === 'premium', $team);

# dispatchUnless

Dispatches a job asynchronously unless the condition is met.

SendTeamReportEmail::dispatchUnless($team->plan === 'free', $team);

# dispatchSync

Dispatches a job synchronously.

SendTeamReportEmail::dispatchSync($team);

# dispatchNow

Dispatches a job synchronously. (Alias of dispatchSync).

SendTeamReportEmail::dispatchNow($team);

# dispatchAfterResponse

Dispatches a job synchronously but only after the response was sent to the user.

SendTeamReportEmail::dispatchAfterResponse($team);

# makeJob

Creates a new JobDecorator that wraps the action. This can be used to dispatch a job using dispatch helper method or when creating a chain of jobs from actions (See withChain).

dispatch(SendTeamReportEmail::makeJob($team));

# makeUniqueJob

Creates a new UniqueJobDecorator that wraps the action. By default, makeJob will automatically return a UniqueJobDecorator if your action implements the ShouldBeUnique trait. However, you may use this method directly to force a UniqueJobDecorator to be created.

dispatch(SendTeamReportEmail::makeUniqueJob($team));

# withChain

Attaches a list of jobs to be executed after the job was processed.

$chain = [
    OptimizeTeamReport::makeJob($team),
    SendTeamReportEmail::makeJob($team),
];

CreateNewTeamReport::withChain($chain)->dispatch($team);

Note that you can achieve the same result by using the chain method on the Bus Facade.

use Illuminate\Support\Facades\Bus;

Bus::chain([
    CreateNewTeamReport::makeJob($team),
    OptimizeTeamReport::makeJob($team),
    SendTeamReportEmail::makeJob($team),
])->dispatch();

# assertPushed

Asserts the action was dispatched.

// Requires the Queue Facade to be fake.
Queue::fake();

// Assert the job was dispatched.
SendTeamReportEmail::assertPushed();

// Assert the job was dispatched 3 times.
SendTeamReportEmail::assertPushed(3);

// Assert a job that satisfies the given callback was dispatched.
SendTeamReportEmail::assertPushed($callback);

// Assert a job that satisfies the given callback was dispatched 3 times.
SendTeamReportEmail::assertPushed(3, $callback);

The callback will receive the following four arguments:

  1. The action itself. Here it would be an instance of SendTeamReportEmail.
  2. The job's arguments. That is, the arguments you provided when calling SendTeamReportEmail::dispatch(...).
  3. The JobDecorator that decorates your action.
  4. The name of the queue that was used.

# assertNotPushed

Asserts the action was not dispatched. See assertPushed for the callback arguments.

// Requires the Queue Facade to be fake.
Queue::fake();

// Assert the job was not dispatched.
SendTeamReportEmail::assertNotPushed();

// Assert a job that satisfies the given callback was not dispatched.
SendTeamReportEmail::assertNotPushed($callback);

# assertPushedOn

Asserts the action was dispatched on a given queue. See assertPushed for the callback arguments.

// Requires the Queue Facade to be fake.
Queue::fake();

// Assert the job was dispatched on the 'reports' queue.
SendTeamReportEmail::assertPushedOn('reports');

// Assert the job was dispatched on the 'reports' queue 3 times.
SendTeamReportEmail::assertPushedOn('reports', 3);

// Assert a job that satisfies the given callback was dispatched on the 'reports' queue.
SendTeamReportEmail::assertPushedOn('reports', $callback);

// Assert a job that satisfies the given callback was dispatched on the 'reports' queue 3 times.
SendTeamReportEmail::assertPushedOn('reports', 3, $callback);

# Methods used

Lists all methods and properties recognised and used by the JobDecorator.

# asJob

Called when dispatched as a job. Uses the handle method directly when no asJob method exists.

class SendTeamReportEmail
{
    use AsAction;

    public function handle(Team $team, bool $fullReport = false): void
    {
        // Prepare report and send it to all $team->users.
    }

    public function asJob(Team $team): void
    {
        $this->handle($team, true);
    }
}

# getJobMiddleware

Adds job middleware directly in the action.

public function getJobMiddleware(): array
{
    return [new RateLimited('reports')];
}

# configureJob

Defines the JobDecorators's option directly in the action.

use Lorisleiva\Actions\Decorators\JobDecorator;

public function configureJob(JobDecorator $job): void
{
    $job->onConnection('my_connection')
        ->onQueue('my_queue')
        ->through(['my_middleware'])
        ->chain(['my_chain'])
        ->delay(60);
}

# $jobConnection

Defines the connection of the JobDecorator. Can also be set using configureJob.

public string $jobConnection = 'my_connection';

# $jobQueue

Defines the queue of the JobDecorator. Can also be set using configureJob.

public string $jobQueue = 'my_queue';

# $jobTries

Defines the number of times the job may be attempted.

public int $jobTries = 10;

# $jobMaxExceptions

Defines the maximum number of exceptions to allow before failing.

public int $jobMaxExceptions = 3;

# $jobBackoff

Defines the number of seconds to wait before retrying the job. Can also be set the getJobBackoff method.

public int $jobBackoff = 60;

# getJobBackoff

Defines the number of seconds to wait before retrying the job.

public function getJobBackoff(): int
{
    return 60;
}

You may also provide an array to provide different backoffs for each retries.

public function getJobBackoff(): array
{
    return [30, 60, 120];
}

# $jobTimeout

Defines the number of seconds the job can run before timing out.

public int $jobTimeout = 60 * 30;

# $jobRetryUntil

Defines the timestamp at which the job should timeout. Can also be set the getJobRetryUntil method.

public int $jobRetryUntil = 1610191764;

# getJobRetryUntil

Defines the time at which the job should timeout.

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

# getJobDisplayName

Customises the display name of the JobDecorator. It provides the same arguments as the asJob method.

public function getJobDisplayName(): string
{
    return 'Send team report email';
}

# getJobTags

Adds some tags to the JobDecorator. It provides the same arguments as the asJob method.

public function getJobTags(Team $team): array
{
    return ['report', 'team:'.$team->id];
}

# getJobUniqueId

Defines the unique key when using the ShouldBeUnique interface. It provides the same arguments as the asJob method.

public function getJobUniqueId(Team $team)
{
    return $this->team->id;
}

# $jobUniqueId

Same as getJobUniqueId but as a property.

public string $jobUniqueId = 'some_static_key';

# getJobUniqueFor

Define the amount of time in which a job should stay unique when using the ShouldBeUnique interface. It provides the same arguments as the asJob method.

public function getJobUniqueFor(Team $team)
{
    return $this->team->role === 'premium' ? 1800 : 3600;
}

# $jobUniqueFor

Same as getJobUniqueFor but as a property.

public int $jobUniqueFor = 3600;

# getJobUniqueVia

Defines the cache driver to use to obtain the lock and therefore maintain the unicity of the jobs being dispatched. Defaults to: the default cache driver.

public function getJobUniqueVia()
{
    return Cache::driver('redis');
}