Bootstrap Twig Components Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codeschubser/bootstrap-twig-components-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Codeschubser\BootstrapTwigComponentsBundle\BootstrapTwigComponentsBundle::class => ['all' => true],
   ];
   

2. First Use Case: Render a basic Bootstrap-aligned button in a Twig template:

   {{ button({
       label: 'Click Me',
       type: 'primary',
       size: 'lg'
   }) }}
   

   Verify the output matches Bootstrap’s styling (e.g., btn-primary class).

3. Key Files:

   • templates/components/ (default Twig component templates).
   • config/packages/bootstrap_twig_components.yaml (customization).

Implementation Patterns

Core Workflows

1. Component Composition: Chain components for complex UIs (e.g., a card with button and alert):

   {{ card({
       header: 'Title',
       body: 'Content',
       footer: button({ label: 'Action', type: 'outline-danger' })
   }) }}
   

2. Dynamic Data Binding: Pass variables from controllers:

   return $this->render('page.html.twig', [
       'items' => $items,
       'user' => $user,
   ]);
   

   Use in Twig:

   {% for item in items %}
       {{ badge({ text: item.status, variant: item.isActive ? 'success' : 'warning' }) }}
   {% endfor %}
   

3. Icon Integration: Embed icons via icon parameter (supports Bootstrap Icons/Font Awesome):

   {{ button({
       label: 'Save',
       icon: 'fa-solid fa-floppy-disk',
       iconPosition: 'left'
   }) }}
   

4. Slot-Based Layouts: Use slot for reusable content blocks (e.g., modals):

   {{ modal({
       title: 'Confirm',
       size: 'sm'
   }) }}
       {{ slot('content') }}
           <p>Are you sure?</p>
       {{ endslot }}
   

Integration Tips

• Asset Management: Ensure Bootstrap CSS/JS is loaded (e.g., via Webpack Encore or Symfony UX Turbo).

  {{ encore_entry_link_tags('app') }}
  

• Custom Templates: Override default templates by copying from vendor/codeschubser/bootstrap-twig-components-bundle/templates/components/ to templates/components/.

• Configuration: Adjust defaults in config/packages/bootstrap_twig_components.yaml:

  bootstrap_twig_components:
      default_icon_set: 'bootstrap'  # or 'fontawesome'
      components:
          button:
              default_type: 'secondary'
  

Gotchas and Tips

Pitfalls

1. Experimental Status:

   • Components may break between minor versions. Pin versions in composer.json:

     "codeschubser/bootstrap-twig-components-bundle": "^1.0.0"
     

2. Icon System Quirks:

   • Font Awesome icons require the library to be loaded (e.g., via CDN or Webpack).
   • Bootstrap Icons need the SVG sprite or font loaded in your assets.

3. Accessibility Gaps:

   • Test aria-* attributes manually. Some components (e.g., modals) may need custom ARIA roles:

     {{ modal({ aria: { 'aria-label': 'User Settings' } }) }}
     

4. Template Overrides:

   • Forgetting to clear the cache after overriding templates:

     php bin/console cache:clear
     

Debugging

• Component Output: Use Twig’s dump to inspect rendered HTML:

  {{ dump(_context) }}
  

  Check for missing classes or malformed attributes.

• Dependency Conflicts: If styles break, verify Bootstrap’s CSS isn’t being overridden. Use browser dev tools to inspect the computed styles.

Extension Points

1. Custom Components: Extend the bundle by creating new Twig components in templates/components/:

   {# templates/components/my_component.html.twig #}
   <div class="my-component {{ variant }}">
       {{ content }}
   </div>
   

   Register in services.yaml:

   twig:
       paths: ['%kernel.project_dir%/templates/components']
   

2. Dynamic Variants: Add logic to support dynamic variants (e.g., for alerts):

   {% macro alert(content, variant='info') %}
       {{ include('components/alert.html.twig', {
           variant: variant,
           content: content
       }) }}
   {% endmacro %}
   

3. Symfony UX Integration: Combine with Symfony UX for reactive components:

   {{ button({
       label: 'Toggle',
       onclick: "this.textContent = 'Toggled'"
   })|raw }}
   

Performance Tips

• Lazy-Load Components: Use Twig’s {% block %} to lazy-load heavy components (e.g., data tables).
• Cache Components: For static content, cache rendered components in the controller:

  $cachedComponent = $this->get('twig')->createTemplate('...')->render([
      'data' => $data,
  ]);
  $this->get('cache')->set('component_key', $cachedComponent, 3600);