PHPackages                             mtownsend/progress - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mtownsend/progress

ActiveLibrary[Utility & Helpers](/categories/utility)

mtownsend/progress
==================

A PHP package to determine steps and progress.

2.0.0(5y ago)22116.2k5MITPHPPHP ~7.4|~8.0

Since Sep 14Pushed 5y ago11 watchersCompare

[ Source](https://github.com/mtownsend5512/progress)[ Packagist](https://packagist.org/packages/mtownsend/progress)[ RSS](/packages/mtownsend-progress/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

A PHP package to determine progress.

[![](https://camo.githubusercontent.com/51a3c8c6854e20b0a40f64de146cd7dfe8cb4aa37374696d438f24da16782103/68747470733a2f2f692e696d6775722e636f6d2f75436a465752442e6a7067)](https://camo.githubusercontent.com/51a3c8c6854e20b0a40f64de146cd7dfe8cb4aa37374696d438f24da16782103/68747470733a2f2f692e696d6775722e636f6d2f75436a465752442e6a7067)

Purpose
-------

[](#purpose)

Walking your users through a process is important for your web app. You want your users to know what you expect of them or a list of requirements that they need to complete.

This progress package is a simple way of taking multiple steps in a process and using them to create a progression system. You can define your steps through an expressive and simple API and let this package handle the heavy lifting. The result is a delightfully easy to use steps-and-progression system.

Simple overview
---------------

[](#simple-overview)

To keep things easy, this package only introduces 2 classes: `Progress` and `Step`. The `Progress` class can accept one or more `Step`s. Each `Step` class is self contained with the data it is evaluating and chainable methods that evaluate the data in a truth test format.

This package utilizes the [beberlei/assert](https://github.com/beberlei/assert) library under the hood to handle all of the truthy statements that the `Step` class uses to evaluate against the data it contains. Every assertion method from [beberlei/assert](https://github.com/beberlei/assert) is chainable on the `Step` class. You can find a list of methods below in the documentation.

Installation
------------

[](#installation)

Install via composer:

```
composer require mtownsend/progress

```

*This package is designed to work with any **PHP 7.4+** application.*

Quick start
-----------

[](#quick-start)

### Using the class

[](#using-the-class)

Here is an example of the most basic usage:

```
use Mtownsend\Progress\Progress;
use Mtownsend\Progress\Step;

$progress = (new Progress(
    (new Step(31, 'Age'))
        ->notEmpty()
        ->integer()
        ->between(18, 65)
))->get();

// Output:
[
  "total_steps" => 1
  "percentage_complete" => 100.0
  "percentage_incomplete" => 0.0
  "steps_complete" => 1
  "steps_incomplete" => 0
  "complete_step_names" => [
    0 => "Age"
  ]
  "incomplete_step_names" => []
]
```

The `Progress` class can accept a single `Step` class or many.

```
use Mtownsend\Progress\Progress;
use Mtownsend\Progress\Step;

$step1 = (new Step('https://marktownsend.rocks', 'Portfolio Site'))->url();
$step2 = (new Step(4, 'Bronze Level Developer'))->integer()->between(1, 5);
$progress = (new Progress($step1, $step2));

$progress->get();

// or an array of Steps
$steps = [
    (new Step('https://marktownsend.rocks', 'Web Site'))->url(),
    (new Step('Laravel Developer', 'Profession'))->notEmpty()->contains('Laravel'),
    (new Step(true, 'Premier Member'))->boolean()->true()
];
$progress = new Progress($steps);

$progress->get();
```

Additionally, if you prefer global helpers, this package auto loads two global helper functions: `progress()` and `step()`. They instantiate each class and accept the exact same arguments. Using the global helpers can reduce your lines of code and eliminate the need to use the `Progress` and `Step` class at the top of your php script - but not all developers prefer global helpers, so it is entirely optional.

```
$step = step('https://marktownsend.rocks', 'Web Site')->url();
$progress = progress($step)->get();

// or an array of Steps
$steps = [
    step('https://marktownsend.rocks', 'Web Site')->url(),
    step('Laravel Developer', 'Profession')->contains('Laravel'),
    step(true, 'Premier Member')->boolean()->true()
];
$progress = progress($steps)->get();
```

The `Progress` class arguments and methods
------------------------------------------

[](#the-progress-class-arguments-and-methods)

The `Progress` class contains 1 optional constructor argument:

```
new Progress(mixed Mtownsend\Progress\Step|array $steps);
```

The `$steps` argument can be a single instance of `\Mtownsend\Progress\Step`, multiple instances as their own argument, or an array of `Step` classes.

However, you can instantiate the `Progress` class without supplying any arguments.

**Methods**

`add(mixed $steps)` Functions exactly the same as the constructor arguments. You can pass a single `Step`, array or multiple instances.

`get()` retrieves the overall progress of your steps. Once it has been called it simply returns the evaluated data. If you want to reuse the class for more progress calculation you will need to instantiate a new `Progress` class to do so.

`toJson()` returns the result of the `Progress` class in valid json.

`toObject()` returns the result of the `Progress` class as a standard PHP object.

**Magic Properties**

If you want to access the results of the `Progress` class without accessing the array of results directly, you can use magic properties that correspond to the key name of the result you want to retrieve.

For example consider the following:

```
$steps = [
    (new Step(42, 'Answer To Everything'))->integer(),
    (new Step('https://github.com/mtownsend5512', 'Github Profile'))->notEmpty()->url(),
    (new Step(10, 'Open Source Packages'))->notEmpty()->integer(),
];
$progress = new Progress($steps);
$progress->get();

// Outputs:
[
  "total_steps" => 3
  "percentage_complete" => 100.0
  "percentage_incomplete" => 0.0
  "steps_complete" => 3
  "steps_incomplete" => 0
  "complete_step_names" => [
    0 => "Answer To Everything"
    1 => "Github Profile"
    2 => "Open Source Packages"
  ]
  "incomplete_step_names" => []
]

// To retrieve percentage_complete you can simply do:
$progress->percentage_complete; // 100.0
```

The `Step` class arguments and methods
--------------------------------------

[](#the-step-class-arguments-and-methods)

**Arguments**

The `Step` class contains 2 constructor arguments:

```
new Step(mixed $data, string $name);
```

The `$data` argument can be anything you wish to evaluate - data from your database, form submission, or other.

`$name` is completely optional, but it can be used to keep track of the step or a label for the step. If you do not assign a name to your `Step`, it will not appear in the `complete_step_names` or `incomplete_step_names` keys, but the failure or success will still be calculated.

### Step arguments and methods

[](#step-arguments-and-methods)

**Methods**

Since the `Step` class wraps around the [beberlei/assert](https://github.com/beberlei/assert) library, you can chain any of the `Assertion` class methods directly on the `Step` class. To see a full list you can view them [directly on the library's readme](https://github.com/beberlei/assert#list-of-assertions), but almost every method you would use has been listed below:

```
$step->alnum()
->base64()
->between(mixed $lowerLimit, mixed $upperLimit)
->betweenExclusive(mixed $lowerLimit, mixed $upperLimit)
->betweenLength(int $minLength, int $maxLength)
->boolean()
->choice(array $choices)
->choicesNotEmpty(array $choices)
->classExists()
->contains(string $needle)
->count(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->date(string $value, string $format)
->defined(mixed $constant)
->digit()
->directory()
->e164()
->email()
->endsWith(string $needle)
->eq(mixed $value)
->eqArraySubset(mixed $value)
->extensionLoaded()
->extensionVersion(string $extension, string $operator, mixed $version)
->false()
->file()
->float()
->greaterOrEqualThan(mixed $limit)
->greaterThan(mixed $limit)
->implementsInterface(mixed $class, string $interfaceName)
->inArray(array $choices)
->integer()
->integerish()
->interfaceExists()
->ip(int $flag = null)
->ipv4(int $flag = null)
->ipv6(int $flag = null)
->isArray()
->isArrayAccessible()
->isCallable()
->isCountable()
->isInstanceOf(string $className)
->isJsonString()
->isObject()
->isResource()
->isTraversable()
->keyExists(string|int $key)
->keyIsset(string|int $key)
->keyNotExists(string|int $key)
->length(int $length)
->lessOrEqualThan(mixed $limit)
->lessThan(mixed $limit)
->max(mixed $maxValue)
->maxCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->maxLength(int $maxLength)
->methodExists(mixed $object)
->min(mixed $minValue)
->minCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)
->minLength(int $minLength)
->noContent()
->notBlank()
->notContains(string $needle)
->notEmpty()
->notEmptyKey(string|int $key)
->notEq(mixed $value)
->notInArray(array $choices)
->notIsInstanceOf(string $className)
->notNull()
->notRegex(string $pattern)
->notSame(mixed $value)
->null()
->numeric()
->objectOrClass()
->phpVersion(string $operator, mixed $version)
->propertiesExist(array $properties)
->propertyExists(string $property)
->range(mixed $minValue, mixed $maxValue)
->readable()
->regex(string $pattern)
->same(mixed $value)
->satisfy(callable $callback)
->scalar(mixed $value)
->startsWith(string $needle)
->string()
->subclassOf(string $className)
->true()
->uniqueValues()
->url()
->uuid()
->version(string $version1, string $operator, string $version2)
->writeable();
```

The `Progress` class handles checking if a `Step` has passed or failed, but in the event you wish to manually check if a `Step` has failed you can call `$step->passed()` which will return a boolean.

Error handling
--------------

[](#error-handling)

In the event you do not supply any `Steps`s to a `Progress` instance and attempt to run the `->get()` method, a `\Mtownsend\Progress\Exceptions\NoStepsException` will be thrown.

Credits
-------

[](#credits)

- Mark Townsend
- [Benjamin Eberlei](https://github.com/beberlei) for his assert library
- [All Contributors](../../contributors)

Testing
-------

[](#testing)

You can run the tests with:

```
./vendor/bin/phpunit
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity41

Moderate usage in the ecosystem

Community13

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

2

Last Release

2065d ago

Major Versions

1.0.0 → 2.0.02020-09-21

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/812987?v=4)[mtownsend](/maintainers/mtownsend)[@mtownsend](https://github.com/mtownsend)

---

Top Contributors

[![mtownsend5512](https://avatars.githubusercontent.com/u/4945553?v=4)](https://github.com/mtownsend5512 "mtownsend5512 (3 commits)")

---

Tags

eligibilityprofile-completionprogressprogress-barstepsprogressbarstepsstepcompletecompletionpercentremainingprogression

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mtownsend-progress/health.svg)

```
[![Health](https://phpackages.com/badges/mtownsend-progress/health.svg)](https://phpackages.com/packages/mtownsend-progress)
```

###  Alternatives

[techlab/smartwizard

The awesome jQuery step wizard plugin

79096.2k2](/packages/techlab-smartwizard)[akaunting/laravel-apexcharts

ApexCharts package for Laravel

84288.3k2](/packages/akaunting-laravel-apexcharts)[smajti1/laravel-wizard

Wizard component for laravel.

409.2k](/packages/smajti1-laravel-wizard)[bramdeleeuw/cookieconsent

GDPR compliant cookie bar and consent checker

1511.5k2](/packages/bramdeleeuw-cookieconsent)[tapp/filament-progress-bar-column

Add beautiful, color-coded progress bars to your Filament table columns. Perfect for inventory, tasks, storage, and any progress metrics without writing custom views.

124.5k](/packages/tapp-filament-progress-bar-column)[bolt/bolt-extension-starter-extended

A description about your extension should go here.

151.1k](/packages/bolt-bolt-extension-starter-extended)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)