Bootstrap4 Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Run:

   composer require alexandermatveev/bootstrap4-bundle alexandermatveev/jquery-bundle alexandermatveev/popper-bundle
   

   Ensure jquery-bundle and popper-bundle are installed as prerequisites.

2. Register the Bundle Add to app/AppKernel.php:

   new AlexanderMatveev\Bootstrap4Bundle\AlexanderMatveevBootstrap4Bundle(),
   

3. Install Assets Symlink assets to your web directory:

   bin/console assets:install --symlink web
   

4. First Use Case Include Bootstrap in a Twig template (e.g., base.html.twig):

   <link href="{{ asset('bundles/alexandermatveevbootstrap4/lib/css/bootstrap.min.css') }}" rel="stylesheet">
   <script src="{{ asset('bundles/alexandermatveevbootstrap4/lib/js/bootstrap.min.js') }}"></script>
   

   Test with a basic component (e.g., a modal):

   <button class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">Launch Modal</button>
   <div class="modal fade" id="exampleModal">
     <div class="modal-dialog">
       <div class="modal-content">
         <div class="modal-header">
           <h5 class="modal-title">Modal Title</h5>
         </div>
         <div class="modal-body">Modal content here.</div>
       </div>
     </div>
   </div>
   

Implementation Patterns

Workflows

1. Asset Management

   • Use asset() helper for paths (e.g., asset('bundles/alexandermatveevbootstrap4/lib/js/bootstrap.bundle.min.js')).
   • For production, enable asset versioning in config/packages/assetic.yaml:

     version: '1.0.*'
     

2. Component Integration

   • Forms: Combine with Symfony’s form_theme (e.g., form_div_layout.html.twig) to style forms with Bootstrap classes.

     {% form_theme form 'bootstrap4_layout.html.twig' %}
     

   • Dynamic Components: Use Twig extensions or JavaScript to toggle Bootstrap features (e.g., tooltips, popovers) dynamically:

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

3. Customization

   • Override default CSS/JS by copying files from vendor/alexandermatveev/bootstrap4-bundle/ to web/bundles/alexandermatveevbootstrap4/ and modify them.
   • Use SASS variables (if using a build tool like Webpack Encore) to customize Bootstrap’s theme.

4. Lazy Loading

   • Load Bootstrap JS only when needed (e.g., for modals) using dynamic imports:

     // In your main JS file
     if (document.querySelector('[data-toggle="modal"]')) {
       import(/* webpackChunkName: "bootstrap" */ 'bootstrap.min.js');
     }
     

Integration Tips

• Symfony UX: Pair with Symfony UX components (e.g., symfony/ux-turbo) for modern interactivity while retaining Bootstrap’s styling.
• Webpack Encore: Replace asset installation with Encore for better bundling:

  // webpack.config.js
  Encore
    .addEntry('bootstrap', './vendor/alexandermatveev/bootstrap4-bundle/lib/js/bootstrap.min.js')
    .enableSingleRuntimeChunk()
    .copyFiles({
      from: './vendor/alexandermatveev/bootstrap4-bundle/lib/css/',
      to: 'bundles/alexandermatveevbootstrap4/lib/css/[name].[ext]',
    });
  

• Twig Extensions: Create a custom Twig extension to generate Bootstrap components:

  // src/Twig/BootstrapExtension.php
  class BootstrapExtension extends \Twig\Extension\AbstractExtension
  {
      public function getFunctions()
      {
          return [
              new \Twig\TwigFunction('bootstrap_button', [$this, 'renderButton']),
          ];
      }
  
      public function renderButton(array $options)
      {
          return sprintf(
              '<button class="btn btn-%s">%s</button>',
              $options['type'] ?? 'primary',
              $options['label']
          );
      }
  }
  

  Usage in Twig:

  {{ bootstrap_button({'label': 'Click', 'type': 'success'}) }}
  

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Hardcoding paths (e.g., /bundles/...) breaks when the bundle is updated. Always use asset().
   • Fix: Use relative paths in Twig (e.g., {% set bootstrap_css = asset('bundles/alexandermatveevbootstrap4/lib/css/bootstrap.min.css') %}).

2. Dependency Conflicts

   • The bundle requires specific versions of jquery-bundle and popper-bundle. Mixing with globally loaded jQuery/Popper may cause issues.
   • Fix: Explicitly load the bundle’s versions:

     <script src="{{ asset('bundles/alexandermatveevjquery/lib/jquery.min.js') }}"></script>
     <script src="{{ asset('bundles/alexandermatveevpopper/lib/popper.min.js') }}"></script>
     

3. Outdated Bundle

   • Last release was in 2018 (Bootstrap 4.0.0). Features like responsive icons or utilities may be missing.
   • Fix: Manually include newer Bootstrap files or fork the bundle.

4. Asset Installation

   • --symlink may fail on some servers. Use --no-debug mode for testing:

     APP_ENV=prod bin/console assets:install --symlink web
     

Debugging

1. Console Errors

   • Check for Uncaught ReferenceError or bootstrap is not defined. Ensure:
     • jQuery and Popper are loaded before Bootstrap JS.
     • No other scripts override $ or jQuery.

2. Component Not Working

   • Verify data attributes (e.g., data-toggle="modal"). Bootstrap 4 uses data-bs-* in newer versions, but this bundle uses the older syntax.
   • Fix: Use the bundle’s syntax or update to Bootstrap 5.

3. CSS Overrides

   • Custom CSS may override Bootstrap styles. Use utility classes or !important sparingly.
   • Fix: Scope custom styles (e.g., .my-component .btn { ... }).

Tips

1. Versioning

   • Pin the bundle version in composer.json to avoid unexpected updates:

     "require": {
         "alexandermatveev/bootstrap4-bundle": "dev-main"
     }
     

2. Performance

   • Bundle includes full Bootstrap JS/CSS. For large apps, consider:
     • Using a CDN for production.
     • Splitting files with Webpack (e.g., extract only needed components).

3. Testing

   • Test components in isolation. Example for a modal:

     // tests/Feature/BootstrapModalTest.php
     public function testModalWorks()
     {
         $this->visitPath('/test-modal');
         $this->click('Launch Modal');
         $this->assertSelectorTextContains('.modal-title', 'Modal Title');
     }
     

4. Extension Points

   • Custom Components: Create a bootstrap_components.html.twig file in your templates directory to override default components.
   • JavaScript Plugins: Extend Bootstrap’s functionality by adding custom JS after bootstrap.min.js:

     <script src="{{ asset('bundles/alexandermatveevbootstrap4/lib/js/bootstrap.min.js') }}"></script>
     <script src="{{ asset('js/custom-bootstrap-plugins.js') }}"></script>
     

5. Configuration

   • The bundle has no built-in config file. For advanced setups, create a config/packages/bootstrap4.yaml:

     bootstrap4:
       enabled: true
       debug: '%kernel.debug%'
       assets:
         css: 'bundles/alexandermatveevbootstrap4/lib/css/bootstrap.min.css'
         js: 'bundles/alexandermatveevbootstrap4/lib/js/bootstrap.min.js'
     

   • Access in Twig:

     {% set bootstrap_css = app.config.bootstrap4.assets.css %}