Bootstrap Indicator Bundle Laravel Package

Getting Started

1. Install the package with Composer and let Laravel's package discovery register the service provider:

   composer require <vendor>/<package>:^1.1
   

2. Publish the config and any front-end views so you can inspect what markup is actually rendered:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Look first at config/<package>.php (or the equivalent config key) — this is where the CSS framework/version is normally declared — and at the published views under resources/views/vendor/<package>/.
3. Set the framework version to bootstrap-3 (or the package's equivalent enum/string) before rendering anything. In v1.1.0 this is the switch that selects the Bootstrap 3 markup path.
4. First use case: drop a single component into an existing Blade layout and confirm the HTML matches what your theme expects. Start with the smallest unit the package exposes (a form field, a button, a single table row), not a full page — it makes version mismatches obvious immediately.

If you are on Bootstrap 5 today, nothing changes: the default path is untouched and the new version flag is opt-in. Upgrade to ^1.1 at your convenience rather than treating this as a migration.

Implementation Patterns

Version selection belongs in config, not in views. Set the framework version once in the published config (and mirror it in .env if the package supports it) so every component renders consistently. Avoid passing a version argument at each call site — it drifts and produces mixed Bootstrap 3 and Bootstrap 5 markup in the same page.

Publish-and-own the views for themed apps. For anything beyond a stock Bootstrap look, publish the views and edit them in resources/views/vendor/<package>/. This is also the cleanest way to bridge gaps the compatibility layer doesn't cover (custom panel headings, brand colours, icon fonts). Remember that published views no longer receive upstream fixes.

Wrap components in a layout partial per framework version. If you maintain more than one app or are migrating incrementally, keep a layouts/bootstrap-3.blade.php and a layouts/bootstrap-5.blade.php and have the components render into whichever the page extends. This keeps the version decision in one place per app rather than smeared across templates.

Integrate with Laravel's paginator deliberately. Pagination is the most common place where framework-version mismatches show up. If the package ships paginator views, publish them and confirm the active version resolves to the Bootstrap 3 markup (ul.pagination > li > a, no page-link classes). Alternatively, call Paginator::useBootstrapThree() in a service provider.

Use it inside existing forms and tables rather than as a whole-page builder. The practical integration is: existing controller → existing Blade view → package components for the repetitive parts (inputs, validation error blocks, table rows, alerts). This limits the blast radius when the package changes and keeps your domain markup in your own templates.

Test the rendered HTML, not just the response status. A feature test asserting assertSee('panel panel-default') (BS3) versus assertSee('card') (BS5) is the cheapest guard against a config regression silently changing your whole UI after a deploy.

Gotchas and Tips

• Bootstrap 3 and 4/5 markup are not interchangeable. Expect the compatibility layer to swap class names (panel/card, pull-right/float-end, form-group/mb-3, input-group-addon/input-group-text, col-xs-*/col-*, hidden-xs/d-none d-sm-block). If a component still emits a modern class while the version is set to 3, that is a bug worth reporting rather than patching locally forever.
• Glyphicons. Bootstrap 3 ships icon classes that Bootstrap 4/5 do not. If the package's BS3 output references glyphicon, you must actually load the Bootstrap 3 CSS or those icons render as empty boxes. Decide early whether you are loading BS3 assets or substituting Font Awesome.
• Config caching. After changing the framework version, run php artisan config:clear (and view:clear if you have published views). A stale cached config is the single most likely reason "the new option does nothing."
• Published views shadow updates. Once you publish, composer update will not touch your copies. When upgrading the package, diff the vendor views against your published ones — this matters more than usual immediately after a compatibility release, since v1.1.0 almost certainly changed the shipped templates.
• Mixed versions on one page. If some components are called through your own wrappers that hardcode classes, you can end up with a BS5 card inside a BS3 grid. Grep your own codebase for framework classes before enabling the BS3 mode, not after.
• CSS is your responsibility. The package renders markup; it does not ship framework CSS. Loading Bootstrap 3 and Bootstrap 5 on the same page will corrupt both — keep one version per layout.
• Extension points to prefer. Config values and published views are the stable surface. Subclassing internal renderer classes or overriding container bindings is fragile and will break on minor releases; if you need behaviour the config can't express, open an issue.
• Scope of this release. v1.1.0 is a single additive feature with no deprecations or breaking changes signalled. There is no migration work — but do re-run your rendering tests after upgrading, because template changes shipped alongside a compatibility flag can alter default output even when the flag is off.