sinemacula/laravel-async-polling

A simple polling trait, designed to extend Laravel's queued jobs with asynchronous polling

v1.0.1 2024-01-29 11:20 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0
• nesbot/carbon: ^2.0

Requires (Dev)

• phpunit/phpunit: ^10.4

Apache-2.0

• Ben Carey

• laravel
• queues
• polling
• sine macula

README

This repository provides a simple polling trait, designed to extend Laravel's queued jobs with asynchronous polling capabilities. It's a straightforward solution for jobs that require repeated checks or waiting for specific conditions before proceeding.

Features

• Effortless Integration: Add polling functionality to any Laravel job with just one trait.
• Customizable Polling Logic: Implement your own polling logic with abstract methods.
• Resource Efficient: Smart handling of execution time and memory limits.

Installation

Install the package via Composer:

composer require sinemacula/laravel-async-polling

Usage

1. Use the Trait in Your Job Class: Import and use HandlesPolling in your Laravel job.

use SineMacula\Jobs\Traits\HandlesPolling;

class ExampleJob implements ShouldQueue
{
    use HandlesPolling;

    // Implement required abstract methods (see Step 2)
}

1. Implement Abstract Methods: Provide implementations for abstract methods defined in the trait to tailor the polling process.

/**
 * Get the id to uniquely identify the polling job.
 *
 * @return string
 */
protected function getPollingId(): string
{
    // Return a unique identifier for the polling job
    
    // Example:
    return $this->uniqueId();
}

/**
 * Determine whether the polling job has resolved.
 *
 * @return bool
 */
protected function hasPollResolved(): bool
{
    // Return true if the polling job has successfully resolved
    
    // Example:
    return $this->isStatusFinite($this->status);
}

/**
 * Resolve the polling job to be dispatched.
 *
 * @return \Illuminate\Contracts\Queue\ShouldQueue
 */
protected function resolvePollingJob(): ShouldQueue
{
    // Resolve the job to be released back to the queue. This function will
    // most likely just return `new static` but it is here to allow for new
    // parameters to be passed to the next instance of the poll. This method
    // will only be executed when job release is not supported.
    
    // Example:
    return new static($this->status);
}

/**
 * Resolve the poll.
 *
 * @return bool
 */
protected function resolvePoll(): bool;
{
    // Here is where you insert the logic for the actual poll
    
    // Example
    $response = SomethingCool::getStatus($this->someProperty);

    $this->someCustomMethod($response);

    return $this->hasPollResolved();
}

1. Customisation Configuration: If you would like to override certain configurations, you can do so by defining any of the following methods:

/**
 * Determine whether jobs can be released.
 *
 * @return bool
 */
protected function canJobsBeReleased(): bool
{
    return config('some.configuration', self::SUPPORTS_JOB_RELEASE);
}

/**
 * Get the interval of the poll.
 *
 * @return int
 */
protected function getInterval(): int
{
    return config('some.configuration', self::DEFAULT_INTERVAL);
}

/**
 * Get the maximum allowed number of attempts.
 *
 * @return int
 */
protected function getMaxAttempts(): int
{
    return config('some.configuration', self::DEFAULT_MAX_ATTEMPTS);
}

/**
 * Get the maximum lifetime of the poll.
 *
 * @return int
 */
protected function getLifetime(): int
{
    return config('some.configuration', self::DEFAULT_LIFETIME);
}

License

The Laravel Async Polling repository is open-sourced software licensed under the Apache License, Version 2.0.