Bootstrap Bundle Laravel Package

Getting Started

First, the stack check — this is the whole assessment. Despite the framing of the task, mazarini/bootstrap-bundle is a Symfony bundle shipping Twig templates, not a Laravel package. It has no service provider, no Blade directives, and no Laravel auto-discovery. Installing it into a Laravel app with composer require gets you files in vendor/ that Laravel will never autoload or render. Before spending any time on integration, confirm your project reality:

• Laravel/Blade project → do not install it. Read the templates as a Bootstrap markup reference and rebuild the parts you need as Blade components (<x-form.input>, <x-alert>) or via a maintained kit like Blade UI Kit or Tall Stack components. Replication cost for the useful 80% (forms, tables, alerts, pagination, layout partials) is a 1–3 day spike.
• Symfony + Twig project that genuinely needs Bootstrap scaffolding → continue below, but read the "Gotchas" section first, because 0 stars / 0 dependents means you are adopting an unmaintained dependency on purpose.

Audit the package in 10 minutes before trusting the README:

composer require mazarini/bootstrap-bundle
find vendor/mazarini/bootstrap-bundle -type f | head -50
cat vendor/mazarini/bootstrap-bundle/composer.json

You are checking three things: the actual PSR-4 namespace (do not guess — copy it from composer.json), whether a templates/ or Resources/views/ tree exists, and which Bootstrap major version the markup targets. Grep the templates for data-bs-toggle (Bootstrap 5) versus data-toggle (Bootstrap 4). That single check decides whether the markup is compatible with your existing UI at all.

Register the bundle manually (no Flex recipe exists for a 0-star package):

// config/bundles.php
return [
    // ...
    Mazarini\BootstrapBundle\MazariniBootstrapBundle::class => ['all' => true],
];

Find the entry point with the debug command:

bin/console debug:twig

Look for the bundle's namespace in the registered paths — that gives you the exact @MazariniBootstrap/... reference usable in {% extends %}. Simultaneously check for a form theme file (*_layout.html.twig, *_theme.html.twig). If one exists, that is the highest-value artifact in the package.

First use case: wire the form theme, not the layout. Layouts are two hours of work to write yourself; correctly overriding Symfony's ~40 form block names is not. If the bundle ships a form theme, adopt that first and evaluate it:

# config/packages/twig.yaml
twig:
    form_themes:
        - '@MazariniBootstrap/form/bootstrap_layout.html.twig'

Render an existing form and inspect the output. If form_row, choice_widget_expanded, and form_errors all carry sane Bootstrap classes, the package has earned its place. If they do not, stop immediately and switch to symfony/twig-bridge's built-in bootstrap_5_layout.html.twig, which is maintained and does the same job.

Implementation Patterns

Treat the bundle as scaffolding, not as your base template. The standard Symfony inheritance pattern applies, but keep the chain shallow and fork early. Extend the bundle layout once, in your own templates/base.html.twig, and override the blocks you care about on day one — so a future composer update cannot silently reshape your pages:

{# templates/base.html.twig #}
{% extends '@MazariniBootstrap/layout.html.twig' %}

{% block stylesheets %}
    {{ parent() }}
    {{ encore_entry_link_tags('app') }}
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    {{ encore_entry_script_tags('app') }}
{% endblock %}

{% block navbar %}
    {# replace the bundle's demo nav with project-specific markup #}
{% endblock %}

Treat any navbar or sidebar block in the upstream layout as a demo you are expected to replace, not as production markup.

Use the component macros as a thin design-system layer. If the package provides macros for alerts, badges, buttons, or modals, import them per-template rather than re-writing class strings inline. Keep your own wrapper macros around them so the import path is centralized:

{% import '@MazariniBootstrap/_macros.html.twig' as ui %}

{{ ui.alert('Saved.', 'success') }}

Do not let raw @MazariniBootstrap imports spread across the codebase. One wrapper file means a future fork-and-vendor migration is a single import change rather than a grep-and-replace across every template.

Keep Bootstrap assets out of the bundle. If the bundle references a CDN or ships its own CSS/JS, ignore it and serve Bootstrap from your normal npm + Encore/Vite pipeline. Two Bootstrap versions on one page is a classic failure mode with bundles of this vintage, and you want your asset version to be the single source of truth. Verify this by inspecting the rendered <head> in dev — if you see two Bootstrap CSS links, you have found the problem.

Port-to-Blade pattern for Laravel shops. If the value you want is the markup, vendor the Twig templates into resources/views/reference/ and mechanically translate to Blade. The replacements are formulaic:

Symfony helper calls (path(), form_*, trans) will not translate directly and are where the real porting effort lives. If the templates call them heavily, the "read it as reference" value collapses and you are better off writing Blade components from scratch against Bootstrap docs.

Wrap the extension points you actually use. If the bundle supports configurable defaults (CSS class prefixes, sizing, button variants), centralize that config in one config/packages/*.yaml block and do not let individual templates override the global defaults. This keeps the design system coherent and makes the day you drop the bundle a config change rather than a template audit.

Gotchas and Tips

The name is the trap. bootstrap-bundle here means "Symfony bundle for Bootstrap," not "bootstrap a project." Zero stars and zero dependents mean no one has validated the package against a real Symfony/Laravel stack in public. Assume no CVE response, no release cadence, and no upgrade guide — because there is no evidence any of those exist. If you adopt it, put that fact in the ADR explicitly, not in a comment nobody reads.

LGPL-3.0 is a legal gate, not an engineering call. Server-rendered templates in a SaaS context is generally low friction, but if you ship an on-prem or packaged distribution and modify the bundle's own source files, you inherit source-disclosure obligations on those modifications. Forking the templates into your own repo under your own license is the clean path; editing the bundle in vendor/ is not (and composer update erases it anyway). Get legal sign-off before adopting, not after.

Never edit vendor/. It is tempting when a template is "almost right." Copy the template into your app's templates/ tree, extend it, and override the offending block — or vendor-fork the whole template directory into resources/ under your own license/attribution. composer update will erase vendor edits, and vendor edits are the exact thing LGPL source-disclosure rules attach to.

Bootstrap version mismatch is the silent breakage. A bundle of this vintage is likely pinned to Bootstrap 4 markup (data-toggle, form-group, input-group-addon) while your app is on Bootstrap 5 (data-bs-toggle, dropped form-group). The pages will render — they will just look subtly wrong and interactive components will silently no-op. Grep before wiring, and if you are on 5, confirm the bundle's markup is 5-compatible or budget the port.

Form theme evaluation is the go/no-go test. If the bundle's form theme overrides form_errors, form_row, choice_widget_expanded, and checkbox_widget with correct Bootstrap classes, it is worth something. If it only overrides form_row, it is not — Symfony's built-in bootstrap_5_layout.html.twig from symfony/twig-bridge covers more ground and is maintained.

Debug rendering with the profiler, not with dd() in a template. Twig debugging via dump() only works with twig.debug: true, and it pollutes rendered markup if it fires in a response. Use bin/console debug:twig to inspect namespaces and bin/console debug:container --tag=twig.extension to confirm any bundle-provided Twig extensions actually registered. If a macro or function "does not exist," it is almost always a namespace or auto-registration problem, not a missing file.

Check composer.json constraints before assuming compatibility. Verify PHP constraint, Symfony versions, and Twig versions against your runtime. A bundle of this vintage may pin symfony/framework-bundle: ^4.4 || ^5.0 and will conflict with Symfony 6/7. If it does, the audit ends there — do not fight the resolver.

Have a removal plan written down on day one. Because there is no upstream to lean on, the honest position is: you own any behavior you depend on. Name an internal owner, put a CODEOWNERS entry on the forked templates if you vendor them, and note in the ADR that Bootstrap version bumps and Symfony version bumps are your responsibility. If nobody is willing to put their name on it, do not adopt it — read it and build in-house instead.

Prefer the maintained path where it exists. For Symfony: symfony/twig-bridge's bootstrap_5_layout.html.twig for forms, twbs/bootstrap via npm for assets, and hand-rolled layout partials for the rest. For Laravel: Blade components plus a maintained UI kit. The only durable contribution of this package is a worked example of Bootstrap markup structure — and reading a template costs nothing while depending on one costs you an owner, a license review, and an upgrade path you no longer control.