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),           // Cache TTL in minutes (default: 19 hours)
    'prefix' => env('PROGRESSABLE_PREFIX', 'progressable'), // Cache key prefix
    'precision' => env('PROGRESSABLE_PRECISION', 2),  // Default decimal precision
];

Usage

This package provides a main trait: Progressable.

With Laravel

The Progressable trait can be used in any class that needs to track progress.

"Local" refers to the progress of your class/model/etc, while "Overall" represents the average of all Progressable instances using the same unique name.

Basic Example

use Verseles\Progressable\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);
            echo "Overall Progress: " . $this->getOverallProgress() . "%" . PHP_EOL;
        }
    }
}

Available Methods

Progress Management

Status Checks

Metadata & Status Messages

Event Callbacks

Configuration

Custom Storage (for non-Laravel usage)

Example with Callbacks and Metadata

use Verseles\Progressable\Progressable;

class FileProcessor
{
    use Progressable;

    public function process(array $files)
    {
        $this->setOverallUniqueName('file-processing')
            ->resetOverallProgress()
            ->onProgressChange(fn($new, $old) => logger("Progress: {$old}% -> {$new}%"))
            ->onComplete(fn() => logger("All files processed!"));

        $increment = 100 / count($files);

        foreach ($files as $index => $file) {
            $this->setStatusMessage("Processing: {$file}")
                ->addMetadata('current_file', $file)
                ->addMetadata('files_processed', $index + 1);

            $this->processFile($file);
            $this->incrementLocalProgress($increment);
        }
    }
}

Without Laravel

You can use the Progressable trait without Laravel by providing custom save and get data callbacks:

use Verseles\Progressable\Progressable;

$storage = [];

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

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

$obj = new class { use Progressable; };
$obj
    ->setCustomSaveData($saveCallback)
    ->setCustomGetData($getCallback)
    ->setOverallUniqueName('my-task')
    ->resetOverallProgress()
    ->setLocalProgress(25);

echo $obj->getLocalProgress(); // 25

Testing

# Run tests
composer test

# Check code style
composer lint:test

# Fix code style
composer lint

# Run static analysis
composer analyse

Contributing

Please see CONTRIBUTING.md for details.

Changelog

Please see CHANGELOG.md for recent changes.

License

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