Library Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require omnia-digital/library
   

   Publish the package assets (if needed):

   php artisan vendor:publish --provider="OmniaDigital\Library\LibraryServiceProvider"
   

2. First Use Case:

   • Modal Dialog: Use the WithModal trait in a Livewire component:

     use OmniaDigital\Library\Traits\WithModal;
     
     class MyComponent extends Component
     {
         use WithModal;
     
         public function mount()
         {
             $this->modal('example-modal', 'Example Title', 'This is a modal content.');
         }
     
         public function render()
         {
             return view('livewire.my-component');
         }
     }
     

   • Notification: Use WithNotification to show toasts:

     use OmniaDigital\Library\Traits\WithNotification;
     
     class MyComponent extends Component
     {
         use WithNotification;
     
         public function showSuccess()
         {
             $this->notify('Success!', 'Operation completed.', 'success');
         }
     }
     

3. Blade Components: Include a form component in your Blade view:

   @livewire('my-component')
   <x-library.text-input wire:model="name" label="Name" />
   

Implementation Patterns

Workflows

1. Component Composition: Combine traits for complex functionality (e.g., WithModal + WithStripe for payment modals):

   use OmniaDigital\Library\Traits\{WithModal, WithStripe};
   
   class PaymentComponent extends Component
   {
       use WithModal, WithStripe;
   
       public function mount()
       {
           $this->modal('payment-modal', 'Payment', view('livewire.payment-form'));
       }
   
       public function handlePayment()
       {
           $this->processStripePayment();
       }
   }
   

2. Data Handling:

   • Sorting: Use WithSorting to manage table columns:

     use OmniaDigital\Library\Traits\WithSorting;
     
     class DataTable extends Component
     {
         use WithSorting;
     
         protected $sortable = ['name', 'created_at'];
     
         public function render()
         {
             return view('livewire.data-table', [
                 'items' => $this->sortData($this->query()->get()),
             ]);
         }
     }
     

   • Caching: Use WithCachedRows for large datasets:

     use OmniaDigital\Library\Traits\WithCachedRows;
     
     class LargeDataset extends Component
     {
         use WithCachedRows;
     
         protected $cacheKey = 'large_dataset';
         protected $cacheDuration = 60; // seconds
     
         public function getItemsProperty()
         {
             return $this->getCachedRows(fn() => $this->query()->get());
         }
     }
     

3. Third-Party Integrations:

   • Stripe: Initialize in mount():

     use OmniaDigital\Library\Traits\WithStripe;
     
     class Checkout extends Component
     {
         use WithStripe;
     
         public function mount()
         {
             $this->initStripe('pk_test_...');
         }
     }
     

   • Maps: Use WithMap for interactive maps:

     use OmniaDigital\Library\Traits\WithMap;
     
     class LocationPicker extends Component
     {
         use WithMap;
     
         public function mount()
         {
             $this->initMap('map-container', [
                 'center' => [40.7128, -74.0060],
                 'zoom' => 12,
             ]);
         }
     }
     

4. Layout Switching: Use WithLayoutSwitcher for grid/list toggles:

   use OmniaDigital\Library\Traits\WithLayoutSwitcher;
   
   class ProductList extends Component
   {
       use WithLayoutSwitcher;
   
       protected $layouts = ['grid', 'list'];
       protected $defaultLayout = 'grid';
   
       public function render()
       {
           return view('livewire.product-list', [
               'products' => $this->getProducts(),
           ]);
       }
   }
   

Integration Tips

1. Livewire 3.x Migration:

   • Replace wire:model with wire:model.live if using Livewire 3.
   • Update trait methods (e.g., emit() → dispatch() for events).

2. Blade Component Aliasing: Add to AppServiceProvider to shorten component names:

   Blade::component('library.text-input', 'text-input');
   

3. Customizing Components: Extend Blade components in resources/views/vendor/library/ to override defaults.

4. Testing: Use Livewire::test() with traits:

   public function test_notification()
   {
       Livewire::test(MyComponent::class)
           ->call('showSuccess')
           ->assertSee('Success!');
   }
   

Gotchas and Tips

Pitfalls

1. Trait Method Conflicts:

   • Traits like WithModal or WithNotification may override existing Livewire methods (e.g., render). Rename or alias if conflicts arise:

     public function renderModal()
     {
         return $this->renderModalContent();
     }
     

2. Livewire 2.x vs. 3.x:

   • Some traits assume Livewire 2.x conventions (e.g., wire:model). Test thoroughly in Livewire 3.x.
   • Check the changelog for breaking changes.

3. Caching Quirks:

   • WithCachedRows uses Laravel’s cache. Clear cache manually if data staleness occurs:

     php artisan cache:clear
     

   • Avoid long cache durations for frequently updated data.

4. Stripe Integration:

   • Ensure WithStripe is initialized after the component is mounted (e.g., in mount()).
   • Handle Stripe errors gracefully:

     try {
         $this->processStripePayment();
     } catch (\Exception $e) {
         $this->notify('Error', $e->getMessage(), 'error');
     }
     

5. Modal Z-Index:

   • Override modal styles if they appear behind other elements:

     .omnia-modal {
         z-index: 9999 !important;
     }
     

Debugging

1. Trait Methods:

   • Use dd() or dump() to inspect trait properties/methods:

     public function debugModal()
     {
         dump($this->modalData);
     }
     

2. Livewire Events:

   • Listen for custom events (e.g., modal-opened):

     $this->listen('modal-opened', function ($modal) {
         dump($modal);
     });
     

3. Blade Component Debugging:

   • Check if components are registered:

     php artisan view:clear
     composer dump-autoload
     

Extension Points

1. Custom Traits:

   • Extend existing traits by creating your own:

     namespace App\Traits;
     
     use OmniaDigital\Library\Traits\WithModal;
     
     trait WithCustomModal
     {
         use WithModal;
     
         public function customModal()
         {
             $this->modal('custom-modal', 'Custom Title', view('custom.view'));
         }
     }
     

2. Component Overrides:

   • Override Blade components in resources/views/vendor/library/:

     resources/
         views/
             vendor/
                 library/
                     components/
                         text-input.blade.php
     

3. Configuration:

   • Publish and customize config:

     php artisan vendor:publish --tag="library-config"
     

   • Modify config/library.php for global settings (e.g., default modal options).

4. Testing Traits:

   • Mock traits in tests:

     $component = Livewire::test(MyComponent::class)
         ->withGlobalTraits([WithModal::class]);