Bootstrap Bundle Laravel Package

Getting Started

This is a Symfony bundle (works fine in Laravel-adjacent PHP stacks only insofar as you can shell out to its commands — there is no Laravel service provider here). It wraps the Bootstrap toolchain: scaffolding, SCSS compilation, and CSS purging via three console commands.

Minimal setup:

1. composer require jbsnewmedia/bootstrap-bundle (requires PHP 8.2+ and Symfony 7.4 components — check your app's PHP/Symfony constraint before pulling this into an older project).
2. Register the bundle in config/bundles.php (Symfony) or add the console commands to your runner if you're wiring it manually.
3. Look first at the bundle's config file under config/packages/ — this is where SCSS entry points, output directories, and purge targets are declared. The README (now with a full German translation and expanded troubleshooting) is the fastest path to the correct key names.
4. Run bootstrap:init to scaffold the expected directory structure and starter SCSS. This is your first use case: it creates the files the other two commands assume exist, so run it before anything else.

The typical first win: point the config at your existing assets/scss/app.scss, run bootstrap:compile, and confirm you get compiled CSS in the configured output dir. Only then introduce bootstrap:purge.

Implementation Patterns

Compile-on-demand in dev, purge-on-build in CI. Wire bootstrap:compile into your local watcher or a Composer script so SCSS changes are picked up without a full asset rebuild. Keep bootstrap:purge out of the dev loop — purging against a dev page set produces misleading results because your local browsing rarely hits every template.

Purge against rendered output, not source. The reliable pattern is: build the app, render the routes/templates you care about (a crawler, a snapshot test, or a static export), then run bootstrap:purge pointed at that HTML. Purge tools work on class names found in markup; scanning Twig/Blade source directly will miss dynamically composed class strings and over-purge.

Chain the commands in a build step. A single CI job running bootstrap:compile → render → bootstrap:purge gives you a deterministic, cacheable artifact. Make the output directory a build artifact rather than a committed file, and let the pipeline own regeneration.

Override Bootstrap variables before compiling. The idiomatic use of an SCSS-based bundle is a custom _variables.scss imported ahead of Bootstrap's own partials. Do this instead of post-processing the compiled CSS — it's the whole reason to compile SCSS rather than ship a CDN link.

Config as the single source of truth. Paths, purge safelists, and output filenames belong in the bundle config, not baked into scripts. Since 1.0.5 refactored compilation and purging into dedicated factory classes with better error reporting, config mistakes now surface as clear console errors instead of silent empty output — lean on that and keep config declarative.

Safelist deliberately. Any class assembled at runtime (btn-{{ $variant }}, JS-toggled classes, classes only present after an AJAX response) needs an explicit safelist entry. Treat the safelist as documentation of your dynamic class surface.

Gotchas and Tips

• This is not a Laravel package. No facade, no service provider, no Blade directives. If you're in Laravel, you're invoking Symfony console commands as a subprocess or via a custom Artisan wrapper. Budget for that impedance mismatch up front.
• PHP 8.2+ and Symfony 7.4 are now explicit targets. The release is backward compatible, but the floor was raised. Legacy apps on PHP 8.0/8.1 or Symfony 5/6 should stay on 1.0.4 or test carefully — the "modern Symfony alignment" line in the changelog is the one to read twice before upgrading.
• Run bootstrap:init before compile or purge. The 1.0.5 error handling now fails earlier and more clearly when expected files are missing, which is an improvement — but it also means a fresh checkout without the scaffolded structure will hard-fail where it might previously have limped along.
• Missing dependencies now throw instead of degrading. The factory refactor reports clearly when SCSS/purge dependencies are absent. If you were relying on a partially-working compile, expect a louder failure. Good news for debugging; check your CI images actually have the required binaries.
• Purging is destructive and content-dependent. Always diff the purged CSS against the compiled CSS on the first run. If the size drop looks implausibly large, your HTML snapshot was incomplete, not your CSS.
• Debugging path: the commands' console output is now more predictable and descriptive (per the changelog). Start there before reaching for -vvv; the improved messages are designed to tell you which path or dependency failed.
• Don't commit build output. Compiled and purged CSS should be reproducible from config + SCSS + a rendered snapshot. Committing it makes purge results unauditable.
• Extension points are factories now. If you need custom compilation or purge behaviour, 1.0.5's dedicated factory classes are the intended seam to override — cleaner than the previous inline logic. This is the main architectural reason to upgrade even if you don't need the new tests.
• Test coverage is the real headline. Commands and services now have comprehensive PHPUnit coverage including edge cases. If you were previously writing workarounds around flaky command behaviour, re-test those scenarios on 1.0.5 before keeping the workarounds.