Bootstrap Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require mopa/bootstrap-bundle
   

   Ensure your composer.json aligns with your Symfony version (e.g., ^4.4|^5.1|^6.0 for v3.4).

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Mopa\Bundle\BootstrapBundle\MopaBootstrapBundle::class => ['all' => true],
   ];
   

3. First Use Case: Inject the MopaBootstrapBundle services into a controller or Twig template:

   {{ mopa_bootstrap_include_css() }}
   {{ mopa_bootstrap_include_js() }}
   

   Render a Bootstrap component (e.g., alert):

   {{ mopa_bootstrap_alert('Success!', 'success') }}
   

4. Key Files:

   • Resources/doc/ for version-specific guides.
   • Resources/views/ for Twig templates (e.g., alert.html.twig).
   • DependencyInjection/Configuration.php for bundle configuration.

Implementation Patterns

Core Workflows

1. Asset Management:

   • Use mopa_bootstrap_include_css() and mopa_bootstrap_include_js() in your base layout (base.html.twig) to avoid duplication.
   • Override asset paths via config:

     # config/packages/mopa_bootstrap.yaml
     mopa_bootstrap:
         assets:
             css: '/custom/path/bootstrap.min.css'
             js: '/custom/path/bootstrap.bundle.min.js'
     

2. Component Integration:

   • Forms: Extend Symfony forms with Bootstrap classes:

     {{ form_widget(form, {'attr': {'class': 'form-control'}}) }}
     

   • Modals/Dropdowns: Use Twig helpers:

     {{ mopa_bootstrap_modal('my-modal', 'Modal Title') }}
     {% block mopa_bootstrap_modal_my_modal_body %}
         <p>Modal content here.</p>
     {% endblock %}
     

3. Dynamic Theming:

   • Switch Bootstrap themes via config:

     mopa_bootstrap:
         theme: 'bootstrap-theme.css'  # e.g., 'bootstrap-theme.min.css'
     

   • Or dynamically in Twig:

     {% set theme = 'bootstrap-theme.css' %}
     {{ mopa_bootstrap_include_css({'theme': theme}) }}
     

4. JavaScript Integration:

   • Initialize plugins (e.g., tooltips) via Twig:

     {{ mopa_bootstrap_javascript('
         $(document).ready(function() {
             $("[data-toggle=tooltip]").tooltip();
         });
     ') }}
     

5. Custom Templates:

   • Override default Twig templates (e.g., alert.html.twig) in:

     templates/bundles/MopaBootstrapBundle/
     

Integration Tips

• Symfony UX: Combine with Symfony UX Turbo/Stimulus for dynamic interactions.
• Webpack Encore: Use encore.addEntry() to bundle Bootstrap assets alongside your JS/CSS.
• Asset Versioning: Enable Symfony’s asset versioning to cache-bust:

  # config/packages/framework.yaml
  assets:
      version: 'unique-version-string'
  

Gotchas and Tips

Pitfalls

1. Asset Loading Order:

   • Issue: Bootstrap JS fails if loaded before jQuery.
   • Fix: Ensure jQuery is loaded first (e.g., via webpack.config.js or twig):

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     {{ mopa_bootstrap_include_js() }}
     

2. Twig Template Overrides:

   • Issue: Custom templates may not inherit parent blocks.
   • Fix: Explicitly extend the base template:

     {% extends 'MopaBootstrapBundle:Component:alert.html.twig' %}
     {% block body %}Custom content{% endblock %}
     

3. Configuration Conflicts:

   • Issue: Config keys may change between versions (e.g., theme vs. bootstrap_theme).
   • Fix: Check DependencyInjection/Configuration.php for the latest schema.

4. Deprecated Methods:

   • Issue: Older versions use mopa_bootstrap_include_assets() (deprecated in v3.4+).
   • Fix: Use mopa_bootstrap_include_css()/mopa_bootstrap_include_js() instead.

5. Symfony 6+ Asset Component:

   • Issue: {{ asset() }} may not work with bundle assets in Symfony 6+.
   • Fix: Use absolute paths or configure the asset component:

     mopa_bootstrap:
         assets:
             base_url: '%env(APP_URL)%/bundles/mopabootstrap'
     

Debugging Tips

1. Check Loaded Assets:

   • Inspect the rendered HTML to verify CSS/JS paths:

     {{ dump(mopa_bootstrap_include_css()) }}
     

2. Enable Debug Mode:

   • Symfony’s debug toolbar shows loaded assets and Twig template inheritance.

3. Clear Cache:

   • After config changes, run:

     php bin/console cache:clear
     

4. Log Configuration:

   • Dump the bundle config to verify settings:

     $this->get('mopa_bootstrap.configuration')->getConfig();
     

Extension Points

1. Custom Components:

   • Create new Twig helpers by extending Mopa\Bundle\BootstrapBundle\Twig\Extension\BootstrapExtension.

2. Asset Pipelines:

   • Override asset paths in config/packages/mopa_bootstrap.yaml or via environment variables.

3. Plugin Initialization:

   • Extend JavaScript initialization by overriding the mopa_bootstrap_javascript block in Twig.

4. Theme Switching:

   • Dynamically load themes based on user preferences:

     {% set theme = app.user.theme ?? 'default' %}
     {{ mopa_bootstrap_include_css({'theme': 'themes/' ~ theme ~ '.css'}) }}
     

5. Symfony Messenger Integration:

   • Use Bootstrap alerts for flash messages:

     {% for message in app.flashes('success') %}
         {{ mopa_bootstrap_alert(message, 'success') }}
     {% endfor %}