verseles/progressable

A Laravel (not only) package to track and manage progress for different tasks or processes.

v2.0.0 2024-05-20 18:59 UTC

Requires

• php: >=8.2
• illuminate/cache: ^11
• illuminate/contracts: ^11
• illuminate/support: ^v11

Requires (Dev)

• orchestra/testbench: ^9.0
• phpunit/phpunit: ^11.1

MIT

• Hélio Oliveira

README

A Laravel (not only) package to track and manage progress for different tasks or processes.

Installation

Install the package via Composer:

composer require verseles/progressable

Optionally, you can publish the config file with:

php artisan vendor:publish --provider="Verseles\Progressable\ProgressableServiceProvider" --tag="config"

Configuration

The published config file provides the following options:

return [
  'ttl' => env('PROGRESSABLE_TTL', 1140), // Default cache time-to-live (in minutes)

  'prefix' => env('PROGRESSABLE_PREFIX', 'progressable'), // Cache key prefix
];

Usage

This package provides a main trait: Progressable.

With Laravel

The Progressable trait can be used in any class that needs to track progress. It provides two main methods: updateLocalProgress and getLocalProgress.

"Local" refers to the progress of your class/model/etc, while "Overall" represents the sum of all Progressable classes using the same key name.

Example

use Verseles\Progressable;

class MyFirstTask
{
    use Progressable;

    public function __construct()
    {
        $this->setOverallUniqueName('my-job')->resetOverallProgress();
    }

    public function run()
    {
        foreach (range(1, 100) as $value) {
            $this->setLocalProgress($value);
            usleep(100000); // Sleep for 100 milliseconds
            echo "Overall Progress: " . $this->getOverallProgress() . "%" . PHP_EOL;
        }
    }
}

use Verseles\Progressable;

class MySecondTask
{
    use Progressable;

    public function __construct()
    {
        $this->setOverallUniqueName('my-job');
    }

    public function run()
    {
        foreach (range(1, 100) as $value) {
            $this->setLocalProgress($value);
            usleep(100000); // Sleep for 100 milliseconds
            echo "Overall Progress: " . $this->getOverallProgress() . "%" . PHP_EOL;
        }
    }
}

• Use setOverallUniqueName to associate the progress with a specific overall progress instance.
• setLocalProgress updates the progress for the current instance.
• getLocalProgress retrieves the current progress.
• getOverallProgress retrieves the overall progress data.
• resetOverallProgress resets the overall progress (recommended after setting the unique name for the first time).

The progress value ranges from 0 to 100.

Without Laravel

You can use the Progressable trait without Laravel by providing custom save and get data methods.

Example

$overallUniqueName = 'test-without-laravel';

$my_super_storage = [];

$saveCallback = function ($key, $data, $ttl) use (&$my_super_storage) {
  $my_super_storage[$key] = $data;
};

$getCallback = function ($key) use (&$my_super_storage) {
  return $my_super_storage[$key] ?? [];
};


$obj1 = new class { use Progressable; };
$obj1
  ->setCustomSaveData($saveCallback)
  ->setCustomGetData($getCallback)
  ->setOverallUniqueName($overallUniqueName)
  ->resetOverallProgress()
  ->updateLocalProgress(25);

$obj2 = new class { use Progressable; };
$obj2
  ->setCustomSaveData($saveCallback)
  ->setCustomGetData($getCallback)
  ->setOverallUniqueName($overallUniqueName)
  ->updateLocalProgress(75);

Testing

To run the tests, execute the following command:

make

License

The Progressable package is open-sourced software licensed under the MIT license.