Bootstrap Twig Components Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add the package via Composer (if not archived, use composer require ebitkov/bootstrap-twig-components).
   • Ensure Symfony UX Twig Components are installed (composer require symfony/ux-twig-component).
   • Register the bundle in config/bundles.php (if applicable).

2. First Use Case:

   • Use a simple Bootstrap component like an alert in a Twig template:

     {% import _self as bootstrap %}
     {{ bootstrap.alert({
         type: 'success',
         message: 'Operation completed successfully!'
     }) }}
     

   • Verify the rendered HTML matches Bootstrap’s expected markup (e.g., role="alert", aria-live).

3. Where to Look First:

   • Check the Symfony UX Twig Components docs for core concepts.
   • Explore the package’s Resources/views/ directory (if available) for component templates.
   • Review the Bootstrap docs for reference markup.

Implementation Patterns

Usage Patterns

1. Component Composition:

   • Chain components for complex layouts (e.g., a card with alert inside):

     {{ bootstrap.card({
         header: 'Title',
         body: bootstrap.alert({ type: 'info', message: 'Details' })
     }) }}
     

   • Pass nested Twig content for dynamic sections (e.g., card.body as a block).

2. Dynamic Attributes:

   • Override Bootstrap’s default attributes via options:

     {{ bootstrap.button({
         label: 'Click me',
         attributes: { 'data-custom': 'value', 'class': 'btn-lg' }
     }) }}
     

   • Use aria-* and role attributes for accessibility (e.g., role="button" for interactive elements).

3. Conditional Rendering:

   • Use Twig’s if to toggle components:

     {% if show_notification %}
         {{ bootstrap.alert({ type: 'warning', message: 'Check your input!' }) }}
     {% endif %}
     

Workflows

1. Laravel Integration:

   • Blade ↔ Twig: Use TwigBridge (e.g., spatie/laravel-twig) to embed Twig components in Blade:

     @twig({{ $componentOptions }})
     

   • Service Providers: Bind the component loader to Laravel’s container for reusable templates.

2. Custom Components:

   • Extend existing components by overriding Twig templates in your project’s Resources/views/ (e.g., bootstrap/alert.html.twig).
   • Create hybrid components by combining Bootstrap + custom logic (e.g., a bootstrap.form with Laravel validation errors).

3. Asset Management:

   • Ensure Bootstrap CSS/JS is loaded (e.g., via Laravel Mix or Vite) for components like modals/carousels to function.

Integration Tips

• Form Integration: Use Symfony’s form_row with Bootstrap components for consistent styling:

  {{ form_row(form.email, { wrapper_class: 'mb-3' }) }}
  

• Responsive Design: Leverage Bootstrap’s classes (e.g., col-md-6) via the attributes option:

  {{ bootstrap.card({ attributes: { class: 'col-md-4' } }) }}
  

• JavaScript Dependencies: For interactive components (e.g., dropdowns), include Bootstrap’s JS:

  {{ bootstrap.script('bootstrap.bundle.js') }}
  

Gotchas and Tips

Pitfalls

1. Archived Status:

   • The package is not maintained. Expect missing components or bugs. Prefer Bootstrap Icons or Tailwind CSS for modern alternatives.
   • Workaround: Fork the repo and extend it for your needs (e.g., add missing components like accordion).

2. Symfony-Specific:

   • Requires Symfony UX Twig Components, which may conflict with Laravel’s templating. Use a wrapper like spatie/laravel-twig carefully.
   • Error: ComponentNotFoundException if the component isn’t implemented. Check the Bootstrap docs for unsupported components.

3. Attribute Overrides:

   • Bootstrap’s default classes (e.g., btn btn-primary) may clash with custom attributes. Use !important sparingly or adjust CSS.

Debugging

1. Template Overrides:

   • If a component renders incorrectly, override its Twig template in your project (e.g., resources/views/components/bootstrap/button.html.twig).
   • Debug Tip: Use {{ dump(component_options) }} to inspect passed options.

2. JavaScript Issues:

   • Components like modals/dropdowns require Bootstrap JS. Verify the script is loaded after the component’s HTML.
   • Debug: Check browser console for Uncaught ReferenceError (missing JS) or TypeError (malformed markup).

3. Caching:

   • Clear Twig cache (php bin/console twig:cache:clear) if changes to templates aren’t reflected.

Tips

1. Partial Components:

   • Use Twig’s {% include %} for reusable snippets (e.g., a bootstrap/_partials/alert.html.twig):

     {% include 'bootstrap/_partials/alert.html.twig' with {
         type: 'danger',
         message: error_message
     } %}
     

2. Accessibility:

   • Ensure role and aria-* attributes are set (e.g., role="alert" for alerts). Override via options if needed:

     {{ bootstrap.alert({ attributes: { 'aria-live': 'polite' } }) }}
     

3. Performance:

   • Lazy-load components with JavaScript (e.g., infinite scroll) by wrapping them in {{ bootstrap.script('...') }}.

4. Testing:

   • Test components in isolation using Symfony’s TwigTest or Laravel’s Pest:

     $twig->render('@bootstrap/alert', ['type' => 'success', 'message' => 'Test']);
     

5. Fallbacks:

   • Provide default content for optional parameters:

     {{ bootstrap.button({
         label: label ?? 'Click',
         attributes: attributes ?? {}
     }) }}