Ui Livewireflux Admin Laravel Package

## Getting Started

### Minimal Steps to First Use
1. **Install the package** via Composer:
   ```bash
   composer require vormiaphp/ui-livewireflux-admin

2. Run the installation command:

   php artisan ui-livewireflux-admin:install
   

3. Verify installation:
   • Check routes/web.php for injected admin routes under auth middleware.
   • Confirm the AdminPanel component exists in app/View/Components/AdminPanel.php.
   • Navigate to /admin in your browser (ensure you’re logged in as an admin).

First Use Case: Managing Categories

• Access the Categories section via /admin/categories.
• The pre-built Livewire component (resources/views/livewire/admin/control/categories/index.blade.php) handles CRUD operations out-of-the-box.
• Use the <x-admin-panel> component in your Blade views for consistent admin layouts:

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

Implementation Patterns

Core Workflows

1. Admin Panel Layouts

   • Use <x-admin-panel> for consistent headers, descriptions, and action buttons.
   • Example:

     <x-admin-panel
         header="Locations"
         desc="Manage countries and cities"
         :button="$createCountryButton"
     >
         @livewire('admin.control.locations.index')
     </x-admin-panel>
     

2. Livewire Component Integration

   • All admin sections (categories, inheritance, locations, etc.) are single-file Livewire components.
   • Extend or override existing components by copying them to app/Livewire/Admin/ and modifying.
   • Example: Override the edit form for categories:

     // app/Livewire/Admin/Control/Categories/Edit.php
     namespace App\Livewire\Admin\Control\Categories;
     use Vormia\UI\LivewireFlux\Admin\Control\Categories\Edit as BaseEdit;
     
     class Edit extends BaseEdit {
         public function updatedCustomField($value) {
             // Custom logic
         }
     }
     

3. Sidebar Menu Injection

   • The package injects admin menu items into the Platform group in Flux’s sidebar.
   • If the sidebar isn’t auto-detected, manually add the snippet from vendor/vormiaphp/ui-livewireflux-admin/src/stubs/reference/sidebar-menu-to-add.blade.php inside:

     <flux:sidebar.group :heading="__('Platform')">
         <!-- Existing items -->
         <!-- PASTE ADMIN MENU ITEMS HERE -->
     </flux:sidebar.group>
     

4. Role-Based Access Control (RBAC)

   • Use Vormia’s Role model (Vormia\Vormia\Models\Role) to assign permissions.
   • Example: Assign a "super admin" role on registration:

     $user = User::create([...]);
     $superAdminRole = Role::where('name', 'super-admin')->first();
     $user->roles()->attach($superAdminRole);
     

5. Customizing Fortify Actions

   • The package publishes Fortify support stubs (e.g., EnsureUserIsActive.php) to app/Actions/Fortify/.
   • Extend these actions for custom logic (e.g., role assignment during registration).

Integration Tips

1. Extending Livewire Components

   • Copy the base Livewire component (e.g., resources/views/livewire/admin/control/categories/index.blade.php) to app/Livewire/Admin/Control/Categories/ and modify.
   • Update the namespace in the copied file to point to your custom class.

2. Adding Custom Admin Sections

   • Follow the existing pattern:
     • Create a Livewire component (e.g., app/Livewire/Admin/CustomSection/Index.php).
     • Add routes in routes/web.php:

       Route::get('/admin/custom-section', [CustomSectionIndex::class, 'index'])->name('admin.custom-section.index');
       

     • Add a menu item to the sidebar:

       <flux:sidebar.item icon="cog" :href="route('admin.custom-section.index')" wire:navigate>
           {{ __('Custom Section') }}
       </flux:sidebar.item>
       

3. Working with Vormia Models

   • The package assumes you’re using Vormia’s models (e.g., Category, Country, City).
   • If you need to customize these, extend Vormia’s base models or create new ones.

4. Flux-Specific Patterns

   • Use Flux’s wire:navigate for smooth transitions between admin pages.
   • Leverage Flux’s flux:sidebar and flux:alert components for consistent UI.

5. Volt Templates (Livewire 4)

   • The package uses Volt for Livewire components. Familiarize yourself with Volt syntax (e.g., @props, @bind, @entangle).
   • Example Volt snippet in a Livewire component:

     <input type="text" wire:model="name" @bind="name">
     

Gotchas and Tips

Pitfalls

1. File Overwrites During Updates

   • Running php artisan ui-livewireflux-admin:update will overwrite your customizations.
   • Solution: Copy custom files to app/ (e.g., app/Livewire/Admin/) before updating.

2. Missing Sidebar Injection

   • If the sidebar menu isn’t injected, check if your sidebar file is named differently (e.g., resources/views/components/sidebar.blade.php).
   • Solution: Manually add the menu snippet from the package’s reference/ folder.

3. Route Injection Failures

   • Routes won’t auto-inject if routes/web.php lacks the auth middleware group.
   • Solution: Manually add the routes from vendor/vormiaphp/ui-livewireflux-admin/src/stubs/reference/routes-to-add.php.

4. Fortify Migration Conflicts

   • If you’ve previously published Fortify migrations, running the install command may cause duplicate column errors.
   • Solution: Remove conflicting migrations or use --force to republish Fortify support stubs:

     php artisan vendor:publish --tag=fortify-support --force
     

5. Volt vs. Blade Confusion

   • Livewire 4 uses Volt by default. If you’re used to Blade, note that syntax differs (e.g., @if vs. @endif in Volt).
   • Tip: Use {{ }} for output in Volt (same as Blade).

6. Role Assignment Issues

   • If roles aren’t attaching to users, ensure the Role model is correctly referenced (Vormia\Vormia\Models\Role).
   • Debug: Check if the role exists in the database:

     Role::all(); // Should return roles like 'user', 'admin', 'super-admin'
     

7. Livewire Component Not Found

   • If a Livewire component (e.g., admin.control.categories.index) isn’t loading, verify:
     • The component file exists in resources/views/livewire/admin/control/categories/index.blade.php.
     • The namespace in the component class matches the file location.

Debugging Tips

1. Check Installed Files

   • Verify files were copied correctly:

     ls app/View/Components/AdminPanel.php
     ls resources/views/livewire/admin/
     

2. Clear Caches

   • After installation/updates, run:

     php artisan optimize:clear
     php artisan view:clear
     

3. Enable Livewire Debugging

   • Add to .env:

     LIVEWIRE_DEBUG=true
     

   • Check Livewire logs for errors:

     storage/logs/livewire.php
     

4. Inspect Flux Sidebar

   • Open your sidebar Blade file and search for <flux:sidebar.group :heading="Platform">. Ensure the admin menu items are inside this group.

5. Test Routes Manually

   • Verify routes exist:

     php artisan route:list | grep admin
     

   • Test a route directly (e.g., /admin/categories).

Extension Points

1. Custom AdminPanel Component

   • Extend app/View/Components/AdminPanel.php to add props or logic:

     public function __construct(
         public string $header,
         public string $desc,
         public View|string $button,
         public ?string $icon = 'cog'
     ) {}
     

2. Hook into Livewire Lifecycle

   • Add custom logic to Livewire components by extending them (e.g., mount(), updatedProperty()):

     protected function mount() {
         $this->customData = 'default';
     }
     

3. Override Fortify Actions

   • Extend app/Actions/Fortify/EnsureUserIsActive.php to add custom validation: