Bootstrap3 Laravel Package

Getting Started

This package is a Composer-delivered Bootstrap 3 asset bundle, not a component library. Expect to read vendor/caouecs/bootstrap3/ rather than documentation — 11 stars and 0 dependents means no README conventions, no maintainer triage, and no community examples to crib from.

Minimum steps:

1. Confirm the stack constraint first. Check the package's composer.json before doing anything else. It almost certainly pins illuminate/support to 4.*/5.* and possibly a PHP >=5.4 platform requirement. If you're on Laravel 6+/PHP 8, Composer will refuse to resolve and the exercise ends here. Do not reach for --ignore-platform-reqs.

2. Install:

   composer require caouecs/bootstrap3
   

3. Register the provider (only if extra.laravel.providers is absent from the package's composer.json — the package predates 5.5 auto-discovery):

   // config/app.php
   'providers' => [
       Caouecs\Bootstrap3\Bootstrap3ServiceProvider::class,
   ],
   

4. Publish the assets — this is the entire runtime behavior of the package:

   # Laravel 5
   php artisan vendor:publish --provider="Caouecs\Bootstrap3\Bootstrap3ServiceProvider"
   # Laravel 4
   php artisan asset:publish caouecs/bootstrap3
   

5. Look first at what actually shipped. Open vendor/caouecs/bootstrap3/ and public/vendor/caouecs/bootstrap3/. Confirm: which Bootstrap 3 patch level (3.3.x vs 3.4.1), whether dist/ or less/ was published, and whether the package ships anything beyond static files. The TPM assessment flags an open question — does it also ship Blade helpers or form macros? — and you should resolve that empirically before designing around it, because it changes removal cost materially.

6. First use case: a single application layout that references the published files.

   {{-- resources/views/layouts/app.blade.php --}}
   <link rel="stylesheet" href="{{ asset('vendor/caouecs/bootstrap3/css/bootstrap.min.css') }}">
   {{-- ... --}}
   <script src="{{ asset('vendor/jquery.min.js') }}"></script>
   <script src="{{ asset('vendor/caouecs/bootstrap3/js/bootstrap.min.js') }}"></script>
   

   Verify those paths against step 5 before copying — hardcoded paths are the single most common source of 404s with this package. Bootstrap 3's JS requires jQuery and requires it to load first; a missing or out-of-order jQuery is a silent no-op, not a console error, in older builds.

Implementation Patterns

Confine it to one layout, extend everywhere. Create layouts/app.blade.php once and @extends it. Use Blade stacks so page-specific CSS/JS don't fight over ordering:

<head>
    <link rel="stylesheet" href="{{ asset('vendor/caouecs/bootstrap3/css/bootstrap.min.css') }}">
    @stack('styles')
</head>
<body>
    @yield('content')
    <script src="{{ asset('vendor/jquery.min.js') }}"></script>
    <script src="{{ asset('vendor/caouecs/bootstrap3/js/bootstrap.min.js') }}"></script>
    @stack('scripts')
</body>

Pagination is the highest-value integration point. Bootstrap 3 markup doesn't match Laravel's default paginator output. On Laravel 5.0–5.2, Illuminate\Pagination\BootstrapThreePresenter is available for free:

// AppServiceProvider::boot()
LengthAwarePaginator::presenter(function ($paginator) {
    return new BootstrapThreePresenter($paginator);
});

On 5.3+ the presenter was removed. Port it into app/Support/, or publish and override pagination::default to emit pagination, page-item, page-link. This is usually the difference between a usable admin screen and an unstyled one.

Forms: lean on Bootstrap 3's has-error / help-block conventions. The $errors bag maps onto them cleanly, so you don't need helpers at all:

<div class="form-group {{ $errors->has('email') ? 'has-error' : '' }}">
    <label for="email" class="control-label">Email</label>
    <input id="email" name="email" type="email"
           class="form-control" value="{{ old('email') }}">
    @if ($errors->has('email'))
        <span class="help-block">{{ $errors->first('email') }}</span>
    @endif
</div>

Cache-bust the published assets. Since you'll re-publish rarely (and by hand), wrap references in a helper that appends filemtime() or a config-driven version string. Without this, patching a CSS file by hand produces stale output for every returning user.

Vendor the assets you actually customized. If you edit the published CSS — theme variables, spacing overrides — copy those files into resources/assets/ and reference them from your build, keeping the package's originals untouched. This makes your overrides reviewable in git and immune to --force republish, which overwrites silently.

Version-pin and record provenance. Note the exact Bootstrap 3 patch level in a comment or an .md in the repo. It matters for CVE tracking (3.4.1 is the last patch, 2019) and because when you eventually vendor the files directly you'll need a reference point.

Migration path, when the time comes. Two clean routes, chosen by whether the UI must stay on Bootstrap 3:

1. Freeze the UI, drop the dependency. Copy bootstrap.min.css / bootstrap.min.js into resources/, or add [email protected] to package.json and reference it through the existing build. Rendered output is identical; the Composer graph is cleaner; the assets become reviewable, version-controlled code. This is reversible and can be done today.
2. Upgrade the UI. Bootstrap 5 removes the jQuery dependency and the EOL advisories. Budget this as a design-system project, not a package swap — pixel parity across a Bootstrap 3 codebase is real work.

Sequence these before the Laravel/PHP upgrade, never in reverse: upgrading the framework while depending on an unmaintained asset package compounds two failure domains.

Gotchas and Tips

Composer resolution will break hard. The constraint can't be satisfied on a Laravel or PHP bump, and composer install fails outright — not gracefully. If you're keeping this in a repo, pin the lockfile and treat any framework upgrade as blocked until the package is removed or forked.

Manual provider registration is permanent config debt. No auto-discovery support means a line in config/app.php that will survive every refactor and confuse the next person. Comment it with a date and the reason.

vendor:publish --force is destructive and silent. It overwrites customized CSS with no diff prompt. Any visual regression is easy to miss in review. The fix is the vendoring pattern above — don't rely on discipline.

jQuery ordering is the most common runtime failure. Bootstrap 3 JS needs jQuery 1.9.1+, loaded before bootstrap.js. On older builds a missing jQuery produces inert components with no console error: modals won't open, dropdowns won't toggle, tooltips won't appear. Check the rendered <head> order in the browser, not the source layout.

Publish destination collisions. The package writes to public/vendor/caouecs/bootstrap3/ (verify). If the app already has a public/css or public/js convention, you'll end up with two sources of truth for styles. Standardize on one before adopting.

Unstyled pages in any environment where publish didn't run. The most frequent deployment failure: assets live in public/, which is typically gitignored, and the publish step isn't in the deploy script. Either commit the published files or add the artisan call to your deploy pipeline — pick one deliberately.

Security review will flag this regardless of delivery mechanism. Bootstrap 3 is EOL with published XSS advisories in tooltip/popover/collapse data-attribute handling (CVE-2019-8331, CVE-2018-14040/14041/14042). The package adds an unpatched distribution point on top. If tooltips or popovers are user-content-driven, treat that as a live issue, not a theoretical one.

No upstream support — plan for it explicitly. Ten stars, zero dependents, single maintainer, no disclosure channel. The practical support model is "read the source, fork it." If you need a fix, you own the fork; don't assume an issue will be triaged.

Extension points basically don't exist. The integration surface is a copy operation. Any customization — form macros, Blade components, layout partials — you write yourself in app/ or resources/, not inside the package. That's the right place anyway: it keeps your additions separable from a future removal.

Debugging checklist, in order: (1) did vendor:publish run in this environment; (2) do the asset() paths match the actual published tree; (3) is jQuery loaded before Bootstrap; (4) which patch level is being served (curl -I the file, or check the banner comment in bootstrap.css); (5) is --force clobbering your overrides. Those five account for the overwhelming majority of issues.

Ramp-up is near-zero; the cost is the debt. No Laravel developer needs more than an hour on this package. The expense is remaining on Laravel 4/5, Bootstrap 3, and jQuery simultaneously — invisible at adoption, expensive at the next platform review.