Fw Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require splittlogic/fw
   

   This installs Livewire (v3.0.10) and Bootstrap (v5.3.2) as dependencies, along with any package-specific configurations.

2. Publish Configurations (if needed): Check if the package includes publishable assets (e.g., Blade views, JS/CSS, or config files) via:

   php artisan vendor:publish --provider="Splittlogic\Fw\FwServiceProvider"
   

   Verify the config/fw.php file exists (if applicable) and adjust settings like default Livewire components or Bootstrap themes.

3. First Use Case:

   • Livewire Integration: Create a Livewire component:

     php artisan make:livewire ExampleComponent
     

     Use Bootstrap classes directly in Blade templates (e.g., <div class="btn btn-primary">).
   • Quick Test: Run the built-in tests to ensure compatibility:

     composer test
     

4. Verify Dependencies: Ensure no conflicts with existing Laravel/Livewire/Bootstrap versions. Check composer.json for version constraints.

Implementation Patterns

Core Workflows

1. Livewire + Bootstrap Integration:

   • Component Styling: Use Bootstrap utility classes (e.g., p-3, bg-light) or components (e.g., <button class="btn btn-outline-danger">) in Livewire Blade views.

     <div class="card">
         <x-livewire:example-component />
     </div>
     

   • Responsive Design: Leverage Bootstrap’s grid system (row, col-*) in Livewire layouts for dynamic content.

2. Asset Management:

   • CSS/JS Bundling: If the package includes custom assets, ensure they’re compiled via Laravel Mix/Vite. Example resources/js/app.js:

     import 'bootstrap';
     import './fw-extensions'; // Hypothetical package-specific JS
     

   • View Composition: Use @stack and @push directives to inject package-specific scripts/styles:

     @push('fw-scripts')
         <script src="{{ asset('fw/js/custom.js') }}"></script>
     @endpush
     

3. Configuration-Driven Features:

   • Customize Livewire defaults (e.g., livewire:init behavior) via config/fw.php:

     'livewire' => [
         'default_component' => 'app.views.Welcome',
         'debug' => env('APP_DEBUG', false),
     ],
     

   • Override Bootstrap variables (e.g., colors, breakpoints) in resources/sass/fw/_variables.scss:

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

4. Modular Component Development:

   • Reusable Components: Create Livewire components that encapsulate Bootstrap-based UI patterns (e.g., modals, alerts):

     // app/Http/Livewire/AlertComponent.php
     public function render()
     {
         return view('livewire.alert-component', [
             'message' => $this->message,
             'type' => $this->type, // 'success', 'danger', etc.
         ]);
     }
     

     <!-- resources/views/livewire/alert-component.blade.php -->
     <div class="alert alert-{{ $type }}">{{ $message }}</div>
     

5. Testing Patterns:

   • Livewire Tests: Use Laravel’s Livewire testing helpers in PHPUnit:

     public function test_component_renders()
     {
         $this->livewire(ExampleComponent::class)
             ->assertSee('Expected Text')
             ->assertSee('btn-primary');
     }
     

   • Bootstrap Styling Tests: Test responsive behavior with browser tools or libraries like laravel-browsershot.

Integration Tips

1. Existing Projects:

   • Run composer why-not splittlogic/fw to check for version conflicts.
   • If using Tailwind, ensure no CSS specificity conflicts with Bootstrap.

2. Livewire + Alpine.js:

   • Combine with Alpine for client-side interactivity:

     <div x-data="{ open: false }">
         <button @click="open = true" class="btn btn-secondary">Toggle</button>
         <x-livewire:modal wire:model="open" />
     </div>
     

3. Package-Specific Features:

   • Check for undocumented features in the CHANGELOG.md (e.g., custom directives like @fwSlot).
   • Monitor for updates via GitHub releases or Packagist.

4. Performance:

   • Lazy-load non-critical Bootstrap JS (e.g., tooltips) with data-bs-toggle:

     <button class="btn btn-info" data-bs-toggle="tooltip" title="Tooltip">Hover</button>
     

   • Use Livewire’s wire:ignore to exclude static elements from reactivity:

     <div wire:ignore>
         <img src="{{ asset('static-image.jpg') }}" class="img-fluid">
     </div>
     

Gotchas and Tips

Pitfalls

1. Version Locking:

   • The package pins Livewire (v3.0.10) and Bootstrap (v5.3.2). Avoid updating these manually to prevent breakage.
   • Fix: Use composer why splittlogic/fw to identify locked versions.

2. Bootstrap JS Conflicts:

   • If using multiple JS frameworks (e.g., jQuery plugins), ensure Bootstrap’s JS is loaded last.
   • Fix: Add to resources/js/app.js:

     import 'bootstrap';
     // Other libraries...
     

3. Livewire + Bootstrap Forms:

   • Bootstrap’s form validation classes (e.g., is-invalid) may conflict with Livewire’s built-in validation.
   • Fix: Use Livewire’s wire:model.error for styling:

     <input wire:model="email" class="form-control {{ $errors->has('email') ? 'is-invalid' : '' }}">
     

4. Asset Pathing:

   • If publishing assets, ensure paths in config/fw.php match your public/ directory structure.
   • Fix: Use Laravel’s mix() helper for asset paths:

     'asset_path' => mix('fw/js/custom.js'),
     

5. Debugging:

   • Livewire: Use php artisan livewire:discover to regenerate component classes.
   • Bootstrap: Clear compiled assets (npm run dev or npm run build) if styles don’t apply.

Debugging Tips

1. Livewire Component Issues:

   • Check the browser’s Network tab for 419/500 errors (CSRF or session issues).
   • Enable Livewire logging in config/fw.php:

     'livewire' => [
         'debug' => true,
     ],
     

2. Bootstrap Styling Problems:

   • Inspect elements to confirm Bootstrap CSS is loaded (check for data-bs-theme attributes).
   • Override variables in resources/sass/fw/_custom.scss:

     @import "bootstrap/scss/bootstrap";
     @import "fw/_variables"; // Override after import
     

3. Package-Specific Quirks:

   • If the package includes custom Blade directives (e.g., @fwComponent), check the FwServiceProvider for registrations:

     Blade::directive('fwComponent', function ($expression) {
         return "<?php echo Splittlogic\Fw\Blade::component($expression); ?>";
     });
     

Extension Points

1. Custom Livewire Components:

   • Extend the package’s base components by creating child classes:

     class ExtendedAlertComponent extends \Splittlogic\Fw\Components\AlertComponent
     {
         public function render()
         {
             $this->message = "Extended: " . parent::getMessage();
             return view('livewire.extended-alert')->layout('layouts.app');
         }
     }
     

2. Bootstrap Theming:

   • Override default Bootstrap variables in resources/sass/fw/_theme.scss:

     $theme-colors: (
         "primary": #0d6efd,
         "secondary": #6c757d
     );
     @import "bootstrap/scss/bootstrap";
     

3. Livewire Hooks:

   • Use Livewire’s lifecycle hooks (e.g., mount(), hydrate()) for package-specific logic:

     public function mount()
     {
         $this->initializeFwDefaults();
     }
     

4. Service Provider Extensions:

   • Bind custom implementations in your AppServiceProvider:

     public function register()
     {
         $this->app->bind(
             \Splittlogic\Fw\Contracts\FwInterface::class,
             \App\Services\CustomFwService::class