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.

For parallel jobs, use one stable overall key for the parent operation and one stable local key per worker. The default cache-backed store updates each local entry independently under a cache lock when the cache driver supports atomic locks. Under heavy contention, Laravel may throw Illuminate\Contracts\Cache\LockTimeoutException if the lock cannot be acquired before the wait timeout.

$progress->setOverallUniqueName("routine-run:{$runId}");
$progress->setLocalKey("module:{$moduleId}");
$progress->setLocalProgress(42);

Custom setCustomSaveData() / setCustomGetData() callbacks still receive the full progress snapshot, so custom storage should implement its own concurrency control for parallel writers.

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.