Bootstrap Bundle Laravel Package

Getting Started

Minimal Setup for Laravel Integration

Since this bundle is designed for Symfony2+, Laravel developers must manually adapt it. Start by:

1. Install via Composer (in Laravel project root):

   composer require alexandermatveev/bootstrap-bundle
   

2. Publish Assets (Laravel’s public folder):

   php artisan vendor:publish --tag=public --force
   

   (Note: The bundle lacks Laravel-specific commands; use assets:install as a fallback.)

3. Register Assets in app.blade.php:

   <!-- CSS -->
   <link href="{{ asset('vendor/alexandermatveev/bootstrap-bundle/css/bootstrap.min.css') }}" rel="stylesheet">
   
   <!-- JS (place before closing </body>) -->
   <script src="{{ asset('vendor/alexandermatveev/bootstrap-bundle/js/bootstrap.min.js') }}"></script>
   

4. Verify Bootstrap Components Work: Test a basic modal or dropdown in a Blade template:

   <button class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">Launch Modal</button>
   <div class="modal fade" id="exampleModal">...</div>
   

Implementation Patterns

1. Asset Management

• Laravel Mix Integration: Replace the bundle’s static assets with Laravel Mix for versioning/optimization:

  // webpack.mix.js
  mix.copy('node_modules/bootstrap/dist/css/bootstrap.min.css', 'public/css');
  mix.copy('node_modules/bootstrap/dist/js/bootstrap.min.js', 'public/js');
  

• Dynamic Asset Paths: Use Laravel’s mix() helper for hashed filenames:

  <link href="{{ mix('css/bootstrap.min.css') }}" rel="stylesheet">
  

2. Component Usage

• Twig vs. Blade: Replace Twig syntax with Blade equivalents:

  <!-- Twig (from bundle docs) -->
  {% block stylesheets %}
      {{ parent() }}
      {{ asset('bundles/alexandermatveevbootstrap/js/bootstrap/css/bootstrap.min.css') }}
  {% endblock %}
  
  <!-- Blade -->
  @vite(['resources/css/bootstrap.min.css'])
  

• Custom Templates: Extend Bootstrap’s components with Laravel’s @include:

  @include('partials.bootstrap.modal', ['title' => 'Custom Modal'])
  

3. JavaScript Dependencies

• jQuery Requirement: Ensure jQuery is loaded before Bootstrap JS:

  <script src="{{ mix('js/jquery.min.js') }}"></script>
  <script src="{{ mix('js/bootstrap.min.js') }}"></script>
  

• Lazy Loading: Use Laravel’s @stack for deferred scripts:

  @stack('scripts')
  

  // In a Blade file
  @push('scripts')
      <script src="{{ mix('js/bootstrap.min.js') }}"></script>
  @endpush
  

4. Configuration

• No Symfony Config: Override defaults via Laravel’s config/bootstrap.php:

  return [
      'version' => '5.3.0', // Custom Bootstrap version
      'assets' => [
          'css' => 'css/bootstrap.custom.min.css',
          'js'  => 'js/bootstrap.custom.min.js',
      ],
  ];
  

  (Note: The bundle lacks a config system; manually manage paths.)

Gotchas and Tips

Pitfalls

1. Symfony-Specific Assumptions:

   • The bundle assumes Symfony’s Asset component. In Laravel, use asset() or mix() instead.
   • Fix: Override the bundle’s Resources/public directory in composer.json:

     "extra": {
         "laravel": {
             "assets": ["public"]
         }
     }
     

2. Outdated Bootstrap Version:

   • The bundle ships Bootstrap 3.3.7 (2018). Modern Laravel projects use Bootstrap 5+.
   • Fix: Replace assets via Laravel Mix or yarn add bootstrap@5.

3. No Laravel Service Provider:

   • The bundle lacks Laravel integration (e.g., no BootstrapServiceProvider).
   • Fix: Create a custom provider to register helpers:

     // app/Providers/BootstrapServiceProvider.php
     public function boot()
     {
         Blade::directive('bootstrapModal', function ($title) {
             return "<?php echo \$this->bootstrapModal($title); ?>";
         });
     }
     

4. Asset Path Confusion:

   • The bundle’s bundles/alexandermatveevbootstrap path won’t exist in Laravel.
   • Fix: Use vendor/alexandermatveev/bootstrap-bundle or symlink:

     ln -s vendor/alexandermatveev/bootstrap-bundle/public web/bootstrap
     

Debugging Tips

• Asset Loading Issues:

  • Verify paths with php artisan route:list or php artisan view:clear.
  • Check browser dev tools for 404s on /vendor/... routes.

• JavaScript Errors:

  • Ensure jQuery is loaded before Bootstrap JS. Test with:

    console.log($); // Should return jQuery function
    

• Component Styling:

  • Override Bootstrap variables via SASS (recommended) or inline CSS:

    /* Override Bootstrap's $primary color */
    .btn-primary {
        background-color: #6f42c1 !important;
    }
    

Extension Points

1. Custom Builds:

   • Use Laravel Mix to compile Bootstrap with custom SASS variables:

     mix.sass('resources/sass/bootstrap-custom.scss', 'public/css');
     

2. Plugin Integration:

   • Extend Bootstrap with plugins (e.g., Bootstrap Icons):

     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css">
     

3. Server-Side Rendering (SSR):

   • For Inertia.js/Vue, dynamically load Bootstrap JS:

     // Inertia page component
     import { usePage } from '@inertiajs/inertia-react';
     const { props } = usePage();
     if (props.requiresBootstrap) {
         import('bootstrap');
     }
     

4. Testing:

   • Mock Bootstrap in PHPUnit:

     // tests/TestCase.php
     public function setUp(): void
     {
         parent::setUp();
         $this->withoutBootstrap(); // Hypothetical helper
     }