Getting Started

Minimal Setup in Laravel

Installation Add the package via Composer (adapting for Symfony compatibility):
```
composer require dontdrinkandroot/bootstrap-bundle
```
Since Laravel doesn’t natively support Symfony bundles, create a Service Provider to bridge the gap:
```
php artisan make:provider BootstrapServiceProvider
```

Register the Bundle In BootstrapServiceProvider.php, register the Symfony bundle:

use DontDrinkAndRoot\BootstrapBundle\BootstrapBundle;

public function register()
{
    $this->app->register(new BootstrapBundle());
}

Publish Assets Use Laravel Mix or Vite to compile Bootstrap’s CSS/JS. The bundle provides Twig integration (not native to Laravel), so manually include Bootstrap’s assets in your resources/views/layouts/app.blade.php:
```
<link href="{{ asset('css/bootstrap.min.css') }}" rel="stylesheet">
<script src="{{ asset('js/bootstrap.bundle.min.js') }}"></script>
```

First Use Case: Basic Components Use Blade directives (not Twig) to render Bootstrap components. Example:

@php
// Simulate Twig's `bootstrap_button` (custom directive)
$buttonClass = 'btn btn-primary';
$buttonText = 'Click Me';
@endphp

<button class="{{ $buttonClass }}">{{ $buttonText }}</button>

Note: For advanced Twig features, consider Laravel-Twig-Bridge.

Implementation Patterns

1. Asset Management

Leverage Laravel Mix/Vite to process Bootstrap’s SCSS/JS:

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/scss/app.scss'],
            refresh: true,
        }),
    ],
});

Include Bootstrap via @import in resources/scss/app.scss:

@import "~bootstrap/scss/bootstrap";

2. Dynamic Components with Blade

Create Blade components to wrap Bootstrap markup:

php artisan make:component Alert

<!-- resources/views/components/alert.blade.php -->
<div class="alert alert-{{ $type ?? 'info' }} alert-dismissible fade show" role="alert">
    {{ $slot }}
    <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
</div>

Usage:

<x-alert type="success">Operation completed!</x-alert>

3. JavaScript Integration

Use Laravel’s mix-manifest.json to reference Bootstrap JS:

<script src="{{ mix('js/app.js') }}"></script>

Initialize Bootstrap components (e.g., modals, tooltips) in resources/js/app.js:

import * as bootstrap from 'bootstrap';
document.addEventListener('DOMContentLoaded', () => {
    new bootstrap.Modal(document.getElementById('myModal'));
});

4. Form Handling

Combine Laravel’s Form Requests with Bootstrap validation styling:

// app/Http/Requests/StoreUserRequest.php
public function rules() { return ['email' => 'required|email']; }

Blade template:

<x-input-error :messages="$errors->get('email')" class="text-danger" />
<input type="email" class="form-control @error('email') is-invalid @enderror">

5. Theming

Override Bootstrap variables in resources/scss/custom.scss:

$primary: #6f42c1;
@import "bootstrap/scss/bootstrap";

Compile via Laravel Mix.

Gotchas and Tips

Pitfalls

Symfony vs. Laravel Ecosystem
- The bundle assumes Twig, not Blade. Workarounds:
  - Use Laravel-Twig-Bridge for Twig templates.
  - Manually replicate Twig logic in Blade (e.g., {% bootstrap_button %} → <button class="btn">).
- Tip: Stick to Blade for simplicity unless Twig-specific features (e.g., extensions) are critical.
Asset Paths
- The bundle doesn’t auto-publish assets. Always use Laravel’s mix() or asset() helpers.
- Gotcha: Forgetting to compile assets after npm install bootstrap.
JavaScript Conflicts
- Bootstrap’s JS relies on jQuery (if using older versions). Ensure compatibility:
```
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="{{ mix('js/bootstrap.bundle.min.js') }}"></script>
```
- Tip: Use Bootstrap 5 (no jQuery dependency) for modern Laravel apps.

Bundle Registration

Symfony bundles require autoloading. Ensure composer.json includes:

"autoload": {
    "psr-4": {
        "DontDrinkAndRoot\\BootstrapBundle\\": "vendor/dontdrinkandroot/bootstrap-bundle/src/"
    }
}

Run composer dump-autoload after installation.

Debugging

Twig Errors in Blade: Use {{ dd($variable) }} to inspect data structures.
CSS/JS Not Loading: Check browser console for 404s. Verify mix-manifest.json paths.

Bundle Not Loading: Clear Laravel cache:

php artisan cache:clear
php artisan config:clear

Extension Points

Custom Twig Extensions If using Twig, extend the bundle’s BootstrapExtension:

// app/Providers/BootstrapServiceProvider.php
public function boot()
{
    $twig = $this->app['twig'];
    $twig->addExtension(new class extends \Twig\Extension\AbstractExtension {
        public function getFunctions() {
            return [
                new \Twig\TwigFunction('custom_alert', [$this, 'renderAlert']),
            ];
        }
        public function renderAlert(string $type, string $message) {
            return sprintf('<div class="alert alert-%s">%s</div>', $type, $message);
        }
    });
}

Laravel Livewire Integration Combine with Livewire for dynamic components:

<x-alert type="success" wire:model="successMessage"></x-alert>

// Livewire component
public $successMessage = "Saved!";

Dark Mode Use Bootstrap’s dark mode with Laravel’s session:

Performance Tips

PurgeCSS: Remove unused Bootstrap classes:

// postcss.config.js
module.exports = {
    plugins: [
        require('purgecss')({
            content: ['resources/**/*.blade.php'],
            defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
        }),
    ],
};

Tree-Shaking: Use Bootstrap’s source files to import only needed components.

Community Workarounds

For Laravel-specific enhancements, check:
- Laravel Bootstrap 5 (alternative package).
- Tailwind CSS (modern alternative to Bootstrap).

Bootstrap Bundle Laravel Package