- What is mrshanebarron/progress and what problem does it solve?
- mrshanebarron/progress is a Laravel UI component package that adds flexible progress tracking to Eloquent models. You define steps or milestones, record completions against a model, and let the package calculate percentages and statuses. It suits onboarding flows, task lists, and other multi-stage processes where you need to show how far along a record is.
- How do I install mrshanebarron/progress in a Laravel application?
- Install it with Composer using composer require mrshanebarron/progress, then publish any package assets if you need to customise the defaults. The v1.0.1 release renamed the published config file to use the sb- prefix, so check the config/ directory after publishing. If vendor:publish --tag= fails or publishes nothing, confirm the tag and filename the package actually registers.
- Which Laravel and PHP versions does this package support?
- The package's technical review did not confirm supported Laravel and PHP versions, so check the require block in its composer.json before adopting it. Verify the constraints match your application's Laravel and PHP versions, and run your test suite on the target version rather than assuming compatibility. On older Laravel releases, confirm the service provider and config merging still behave as expected.
- How do I define steps or milestones on an Eloquent model?
- Add the package's trait to the Eloquent model you want to track, then declare the steps or milestones that make up the process. The exact API comes from the package's contracts, so follow its trait and config definitions instead of hardcoding step names in your app. Keep step keys stable in config so historical completion records stay valid.
- How do I record a completion and check the percentage or status?
- Once steps are defined, you mark a step complete for a given model instance and the package derives progress from those records. Percentages and statuses are calculated from completed versus total steps, so avoid duplicating that math in your own code. Persist completions in the database rather than in memory so the values survive requests and queue workers.
- Can I use this package for onboarding checklists, tasks, and multi-stage workflows?
- Yes. The package is designed for multi-stage processes such as onboarding checklists, task tracking, and workflow milestones. Because progress is stored per model, the same definitions can drive dashboards, reminder nudges, and eligibility checks. Keep step definitions in config so changes do not require new migrations.
- Why did my config overrides stop applying after upgrading to v1.0.1?
- v1.0.1 renames the published config file to the sb- prefix, so an app still loading the old filename silently falls back to package defaults instead of erroring. Re-publish with php artisan vendor:publish --force, diff it against your old file, and port any overrides. Also inspect config/ and bootstrap/cache/config.php to confirm which filename the app actually loads, then clear the cached config.
- Is upgrading from v1.0.0 to v1.0.1 a breaking change?
- For consumers who rely on package defaults it is effectively non-breaking, but it is backward-incompatible for anyone who already published the v1.0.0 config and edited it. Treat it as a minor-with-caveat rather than a clean patch, and grep your app code, tests, and deployment scripts for hardcoded references to the old filename. Pin v1.0.1 only after verifying your overrides still apply.
- How do I test progress tracking in my Laravel test suite?
- Use Laravel's normal feature-test tooling: RefreshDatabase, model factories, and assertions against the package's percentage and status values. Publish the config in your test environment so tests exercise the same step definitions as production. Add tests for the zero-progress and fully-complete cases, which catches config drift early.
- What should I check before pinning v1.0.1 in production?
- Confirm which config filename the application loads by inspecting config/ and bootstrap/cache/config.php before and after the upgrade. Re-publish and diff the config, grep for hardcoded references to the old filename, and clear the config cache. Because a stale file falls back to defaults silently, explicitly verify your custom settings still take effect rather than relying on the absence of errors.