Ui Livewireflux Admin Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require vormiaphp/ui-livewireflux-admin
   php artisan ui-livewireflux-admin:install
   

2. Verify installation:

   • Check routes/web.php for injected admin routes.
   • Confirm AdminPanel component exists in app/View/Components/AdminPanel.php.
   • Ensure sidebar menu items appear in your Flux sidebar.

3. First use case: Access /admin/categories to manage categories via the pre-built Livewire component. Use the AdminPanel component in your Blade views:

   <x-admin-panel header="Categories" desc="Manage your categories">
       @livewire('admin.control.categories.index')
   </x-admin-panel>
   

Where to Look First

• Livewire components: resources/views/livewire/admin/
• AdminPanel component: app/View/Components/AdminPanel.php
• Sidebar integration: resources/views/layouts/app/sidebar.blade.php or resources/views/components/layouts/app/sidebar.blade.php
• Documentation: docs/GUIDE.md (roles, Fortify, layout patterns)

Implementation Patterns

Usage Patterns

1. Admin Panel Layout: Use the AdminPanel component to wrap Livewire components for consistent styling and metadata:

   <x-admin-panel header="Admins" :button="$createButton">
       @livewire('admin.admins.index')
   </x-admin-panel>
   

2. Livewire Component Workflow:

   • Index: List records (@livewire('admin.control.categories.index')).
   • Create/Edit: Use dedicated Livewire components (@livewire('admin.control.categories.create')).
   • Reusable Logic: Extend base Livewire classes (e.g., AdminTable) for shared functionality like pagination or search.

3. Sidebar Integration: Inject admin menu items into the Platform Flux group:

   <flux:sidebar.group :heading="__('Platform')">
       <!-- Existing items -->
       <flux:sidebar.item icon="users" :href="route('admin.admins.index')" wire:navigate>
           {{ __('Admins') }}
       </flux:sidebar.item>
   </flux:sidebar.group>
   

4. Role Assignment: Attach roles to users during registration:

   $user->roles()->attach(Role::where('name', 'admin')->first());
   

5. Customizing Components: Extend Livewire components (e.g., app/Livewire/Admin/CustomCategories.php) and override methods like mount() or rules().

Workflows

1. CRUD Operations:

   • Use the pre-built Livewire components for categories, locations, etc.
   • Example: Edit a category at /admin/categories/edit/{id}.

2. Fortify Integration:

   • Extend EnsureUserIsActive for custom user validation.
   • Publish Fortify migrations if needed:

     php artisan vendor:publish --tag=fortify-migrations
     php artisan migrate
     

3. Dynamic Admin Routes: Register custom admin routes in routes/web.php:

   Route::prefix('admin')->middleware(['auth'])->group(function () {
       Route::get('/custom', [CustomAdminController::class, 'index']);
   });
   

4. Volt Templates: Leverage Volt syntax in Livewire components for concise Blade-like syntax:

   <x-admin-panel header="Availability">
       @livewire('admin.control.availability.index')
   </x-admin-panel>
   

Integration Tips

• Vormia Ecosystem: Use Vormia models (e.g., Vormia\Vormia\Models\Role) for consistency.
• Flux Theming: Customize Flux styles in resources/css/flux/app.css to match your admin panel.
• Livewire Events: Dispatch events from Livewire components to trigger global updates (e.g., emit('admin-updated')).
• Backup Customizations: Store overrides in app/Livewire/Admin/ to avoid losing changes during updates.

Gotchas and Tips

Pitfalls

1. File Overwrites:

   • Customizations to resources/views/livewire/admin/ or app/View/Components/AdminPanel.php will be lost on updates.
   • Fix: Extend components (e.g., app/Livewire/Admin/CustomCategories.php) instead of modifying package files.

2. Sidebar Injection:

   • Menu items are injected into the Platform Flux group. If your sidebar structure differs, manually add items.
   • Fix: Check resources/views/layouts/app/sidebar.blade.php for the correct group.

3. Route Injection:

   • Routes are injected into the auth middleware group in routes/web.php. If this group doesn’t exist, routes won’t auto-inject.
   • Fix: Manually add routes or ensure the middleware group exists.

4. Fortify Dependencies:

   • The package requires laravel/fortify ^1.34. Mismatched versions may cause issues.
   • Fix: Run composer require laravel/fortify:^1.34 if conflicts arise.

5. Volt Compatibility:

   • Volt is bundled with Livewire 4. Ensure your project uses Livewire 4+.
   • Fix: Update Livewire:

     composer require livewire/livewire:^4.1
     

6. Role Model Conflicts:

   • Roles are tied to Vormia\Vormia\Models\Role. Custom role models may break functionality.
   • Fix: Use Vormia’s role model or alias it in your config.

Debugging

1. Missing Sidebar Items:

   • Verify the Platform Flux group exists in your sidebar file.
   • Check for typos in route names (e.g., admin.admins.index).

2. Livewire Component Not Loading:

   • Ensure the component class exists (e.g., app/Livewire/Admin/Admins/Index.php).
   • Clear Livewire and Blade caches:

     php artisan view:clear
     php artisan livewire:discover
     

3. Route Not Found:

   • Confirm the route is injected into routes/web.php.
   • Check for middleware conflicts (e.g., auth or verified).

4. Fortify Errors:

   • Ensure EnsureUserIsActive is registered in Fortify’s AuthenticatedSessionController.
   • Verify Fortify migrations are up-to-date:

     php artisan migrate
     

Tips

1. Backup Before Updating:

   • Use the built-in backup system:

     php artisan ui-livewireflux-admin:update
     

   • Backups are stored in storage/app/ui-livewireflux-admin-backups/.

2. Custom Admin Routes:

   • Extend the route registration logic in app/Providers/RouteServiceProvider.php:

     public function boot()
     {
         parent::boot();
         $this->registerAdminRoutes();
     }
     

3. Livewire Flux Integration:

   • Use Flux’s wire:navigate for smooth transitions between admin pages:

     <flux:sidebar.item :href="route('admin.categories.index')" wire:navigate>
         Categories
     </flux:sidebar.item>
     

4. Performance:

   • Lazy-load Livewire components for large datasets:

     public function mount()
     {
         $this->loadData = false;
     }
     

     @if($loadData)
         @livewire('admin.control.categories.index')
     @endif
     

5. Testing:

   • Test admin routes with Laravel’s testing tools:

     $response = $this->actingAs($adminUser)->get('/admin/categories');
     $response->assertStatus(200);
     

6. Extension Points:

   • Override Livewire methods in custom components:

     public function updatedSearch()
     {
         $this->resetPage();
         $this->loadData = true;
     }
     

   • Extend the AdminPanel component for custom headers/footers:

     public function render()
     {
         return view('components.admin-panel', [
             'header' => $this->header ?? 'Default Header',
         ]);
     }