{"id":22917424,"url":"https://github.com/mtownsend5512/progress","last_synced_at":"2025-04-06T01:09:55.287Z","repository":{"id":57021638,"uuid":"295459574","full_name":"mtownsend5512/progress","owner":"mtownsend5512","description":"A PHP package to determine steps and progress.","archived":false,"fork":false,"pushed_at":"2020-09-21T20:56:00.000Z","size":1131,"stargazers_count":220,"open_issues_count":0,"forks_count":5,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-30T00:08:37.700Z","etag":null,"topics":["eligibility","profile-completion","progress","progress-bar","steps"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtownsend5512.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-14T15:32:19.000Z","updated_at":"2025-01-06T13:20:56.000Z","dependencies_parsed_at":"2022-08-23T13:50:50.895Z","dependency_job_id":null,"html_url":"https://github.com/mtownsend5512/progress","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtownsend5512%2Fprogress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtownsend5512%2Fprogress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtownsend5512%2Fprogress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtownsend5512%2Fprogress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtownsend5512","download_url":"https://codeload.github.com/mtownsend5512/progress/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419861,"owners_count":20936012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eligibility","profile-completion","progress","progress-bar","steps"],"created_at":"2024-12-14T06:17:53.419Z","updated_at":"2025-04-06T01:09:55.268Z","avatar_url":"https://github.com/mtownsend5512.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"A PHP package to determine progress.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://i.imgur.com/uCjFWRD.jpg\"\u003e\n\u003c/p\u003e\n\n## Purpose\n\nWalking 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.\n\nThis 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.\n\n## Simple overview\n\nTo 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.\n\nThis 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.\n\n## Installation\n\nInstall via composer:\n\n```\ncomposer require mtownsend/progress\n```\n\n*This package is designed to work with any **PHP 7.4+** application.*\n\n## Quick start\n\n### Using the class\n\nHere is an example of the most basic usage:\n\n```php\nuse Mtownsend\\Progress\\Progress;\nuse Mtownsend\\Progress\\Step;\n\n$progress = (new Progress(\n    (new Step(31, 'Age'))\n        -\u003enotEmpty()\n        -\u003einteger()\n        -\u003ebetween(18, 65)\n))-\u003eget();\n\n// Output:\n[\n  \"total_steps\" =\u003e 1\n  \"percentage_complete\" =\u003e 100.0\n  \"percentage_incomplete\" =\u003e 0.0\n  \"steps_complete\" =\u003e 1\n  \"steps_incomplete\" =\u003e 0\n  \"complete_step_names\" =\u003e [\n    0 =\u003e \"Age\"\n  ]\n  \"incomplete_step_names\" =\u003e []\n]\n```\n\nThe `Progress` class can accept a single `Step` class or many.\n\n```php\nuse Mtownsend\\Progress\\Progress;\nuse Mtownsend\\Progress\\Step;\n\n$step1 = (new Step('https://marktownsend.rocks', 'Portfolio Site'))-\u003eurl();\n$step2 = (new Step(4, 'Bronze Level Developer'))-\u003einteger()-\u003ebetween(1, 5);\n$progress = (new Progress($step1, $step2));\n\n$progress-\u003eget();\n\n// or an array of Steps\n$steps = [\n    (new Step('https://marktownsend.rocks', 'Web Site'))-\u003eurl(),\n    (new Step('Laravel Developer', 'Profession'))-\u003enotEmpty()-\u003econtains('Laravel'),\n    (new Step(true, 'Premier Member'))-\u003eboolean()-\u003etrue()\n];\n$progress = new Progress($steps);\n\n$progress-\u003eget();\n```\n\nAdditionally, 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.\n\n```php\n$step = step('https://marktownsend.rocks', 'Web Site')-\u003eurl();\n$progress = progress($step)-\u003eget();\n\n// or an array of Steps\n$steps = [\n    step('https://marktownsend.rocks', 'Web Site')-\u003eurl(),\n    step('Laravel Developer', 'Profession')-\u003econtains('Laravel'),\n    step(true, 'Premier Member')-\u003eboolean()-\u003etrue()\n];\n$progress = progress($steps)-\u003eget();\n```\n\n## The `Progress` class arguments and methods\n\nThe `Progress` class contains 1 optional constructor argument:\n\n```php\nnew Progress(mixed Mtownsend\\Progress\\Step|array $steps);\n```\n\nThe `$steps` argument can be a single instance of `\\Mtownsend\\Progress\\Step`, multiple instances as their own argument, or an array of `Step` classes. \n\nHowever, you can instantiate the `Progress` class without supplying any arguments.\n\n**Methods**\n\n`add(mixed $steps)` Functions exactly the same as the constructor arguments. You can pass a single `Step`, array or multiple instances.\n\n`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.\n\n`toJson()` returns the result of the `Progress` class in valid json.\n\n`toObject()` returns the result of the `Progress` class as a standard PHP object.\n\n**Magic Properties**\n\nIf 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.\n\nFor example consider the following:\n\n```php\n$steps = [\n    (new Step(42, 'Answer To Everything'))-\u003einteger(),\n    (new Step('https://github.com/mtownsend5512', 'Github Profile'))-\u003enotEmpty()-\u003eurl(),\n    (new Step(10, 'Open Source Packages'))-\u003enotEmpty()-\u003einteger(),\n];\n$progress = new Progress($steps);\n$progress-\u003eget();\n\n// Outputs:\n[\n  \"total_steps\" =\u003e 3\n  \"percentage_complete\" =\u003e 100.0\n  \"percentage_incomplete\" =\u003e 0.0\n  \"steps_complete\" =\u003e 3\n  \"steps_incomplete\" =\u003e 0\n  \"complete_step_names\" =\u003e [\n    0 =\u003e \"Answer To Everything\"\n    1 =\u003e \"Github Profile\"\n    2 =\u003e \"Open Source Packages\"\n  ]\n  \"incomplete_step_names\" =\u003e []\n]\n\n// To retrieve percentage_complete you can simply do:\n$progress-\u003epercentage_complete; // 100.0\n```\n\n\n## The `Step` class arguments and methods\n\n**Arguments**\n\nThe `Step` class contains 2 constructor arguments:\n\n```php\nnew Step(mixed $data, string $name);\n```\n\nThe `$data` argument can be anything you wish to evaluate - data from your database, form submission, or other.\n\n`$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.\n\n### Step arguments and methods\n\n**Methods**\n\nSince 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:\n\n```php\n$step-\u003ealnum()\n-\u003ebase64()\n-\u003ebetween(mixed $lowerLimit, mixed $upperLimit)\n-\u003ebetweenExclusive(mixed $lowerLimit, mixed $upperLimit)\n-\u003ebetweenLength(int $minLength, int $maxLength)\n-\u003eboolean()\n-\u003echoice(array $choices)\n-\u003echoicesNotEmpty(array $choices)\n-\u003eclassExists()\n-\u003econtains(string $needle)\n-\u003ecount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)\n-\u003edate(string $value, string $format)\n-\u003edefined(mixed $constant)\n-\u003edigit()\n-\u003edirectory()\n-\u003ee164()\n-\u003eemail()\n-\u003eendsWith(string $needle)\n-\u003eeq(mixed $value)\n-\u003eeqArraySubset(mixed $value)\n-\u003eextensionLoaded()\n-\u003eextensionVersion(string $extension, string $operator, mixed $version)\n-\u003efalse()\n-\u003efile()\n-\u003efloat()\n-\u003egreaterOrEqualThan(mixed $limit)\n-\u003egreaterThan(mixed $limit)\n-\u003eimplementsInterface(mixed $class, string $interfaceName)\n-\u003einArray(array $choices)\n-\u003einteger()\n-\u003eintegerish()\n-\u003einterfaceExists()\n-\u003eip(int $flag = null)\n-\u003eipv4(int $flag = null)\n-\u003eipv6(int $flag = null)\n-\u003eisArray()\n-\u003eisArrayAccessible()\n-\u003eisCallable()\n-\u003eisCountable()\n-\u003eisInstanceOf(string $className)\n-\u003eisJsonString()\n-\u003eisObject()\n-\u003eisResource()\n-\u003eisTraversable()\n-\u003ekeyExists(string|int $key)\n-\u003ekeyIsset(string|int $key)\n-\u003ekeyNotExists(string|int $key)\n-\u003elength(int $length)\n-\u003elessOrEqualThan(mixed $limit)\n-\u003elessThan(mixed $limit)\n-\u003emax(mixed $maxValue)\n-\u003emaxCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)\n-\u003emaxLength(int $maxLength)\n-\u003emethodExists(mixed $object)\n-\u003emin(mixed $minValue)\n-\u003eminCount(array|Countable|ResourceBundle|SimpleXMLElement $countable, int $count)\n-\u003eminLength(int $minLength)\n-\u003enoContent()\n-\u003enotBlank()\n-\u003enotContains(string $needle)\n-\u003enotEmpty()\n-\u003enotEmptyKey(string|int $key)\n-\u003enotEq(mixed $value)\n-\u003enotInArray(array $choices)\n-\u003enotIsInstanceOf(string $className)\n-\u003enotNull()\n-\u003enotRegex(string $pattern)\n-\u003enotSame(mixed $value)\n-\u003enull()\n-\u003enumeric()\n-\u003eobjectOrClass()\n-\u003ephpVersion(string $operator, mixed $version)\n-\u003epropertiesExist(array $properties)\n-\u003epropertyExists(string $property)\n-\u003erange(mixed $minValue, mixed $maxValue)\n-\u003ereadable()\n-\u003eregex(string $pattern)\n-\u003esame(mixed $value)\n-\u003esatisfy(callable $callback)\n-\u003escalar(mixed $value)\n-\u003estartsWith(string $needle)\n-\u003estring()\n-\u003esubclassOf(string $className)\n-\u003etrue()\n-\u003euniqueValues()\n-\u003eurl()\n-\u003euuid()\n-\u003eversion(string $version1, string $operator, string $version2)\n-\u003ewriteable();\n```\n\nThe `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-\u003epassed()` which will return a boolean.\n\n## Error handling\n\nIn the event you do not supply any `Steps`s to a `Progress` instance and attempt to run the `-\u003eget()` method, a `\\Mtownsend\\Progress\\Exceptions\\NoStepsException` will be thrown.\n\n## Credits\n\n- Mark Townsend\n- [Benjamin Eberlei](https://github.com/beberlei) for his assert library\n- [All Contributors](../../contributors)\n\n## Testing\n\nYou can run the tests with:\n\n```bash\n./vendor/bin/phpunit\n```\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtownsend5512%2Fprogress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtownsend5512%2Fprogress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtownsend5512%2Fprogress/lists"}