README

A Laravel package that provides a complete admin panel solution with pre-built components, routes, and views for managing categories, inheritance, locations, availability, and admin users. Built with Livewire Volt and Flux for a modern, reactive admin interface.

What is This Package?

Vormia UI Livewire Flux Admin is a comprehensive admin panel package for Laravel applications that includes:

AdminPanel View Component - A reusable Blade component for consistent admin panel layouts
Pre-configured Admin Routes - Complete CRUD routes for all admin sections
Livewire Volt Components - Single-file components for categories, inheritance, locations, availability, and admin management
Automatic Sidebar Integration - Sidebar menu injection (when livewire/flux is installed)
Role Management - Automatic role attachment for new users (when laravel/fortify is installed)

This package is designed to work seamlessly with the Vormia ecosystem and follows Laravel best practices.

Prerequisites

Before installing this package, ensure you have the following required packages installed:

Required Packages

PHP >= 8.2
Laravel Framework >= 12.0
vormiaphp/vormia >= 2.0 (or ^3.0 or ^4.0)
livewire/volt >= 1.0

Install the required packages:

Note: If vormiaphp/vormia is already installed, skip this process. This applies only for standalone installation.

composer require vormiaphp/vormia
composer require livewire/volt

Optional Packages

The following packages are optional but provide enhanced functionality:

livewire/flux

Purpose: Provides automatic sidebar menu injection with Flux navigation components.

If installed:

Sidebar menu items are automatically added to your sidebar view
Navigation links use Flux components for consistent styling

If NOT installed:

You'll need to manually add navigation links to your sidebar
The installation process will warn you and provide instructions

Installation:

composer require livewire/flux

laravel/fortify

Purpose: Enables automatic role attachment for newly registered users.

If installed:

The CreateNewUser action is automatically updated
New users are automatically assigned the admin role (ID: 1)

If NOT installed:

You'll need to manually attach roles to new users
The installation process will warn you and provide instructions

Installation:

composer require laravel/fortify

Installation Process

Step 1: Install the Package

composer require vormiaphp/ui-livewireflux-admin

Step 2: Run the Installation Command

php artisan ui-livewireflux-admin:install

This command will:

✅ Check for required dependencies
✅ Copy all package files to your application
✅ Inject routes into routes/web.php
✅ Inject sidebar menu (if livewire/flux is installed)
✅ Update CreateNewUser action (if laravel/fortify is installed)
✅ Clear application caches

Step 3: Verify Installation

After installation, verify that:

Files were copied to app/View/Components/AdminPanel.php
Routes were added to routes/web.php
Sidebar menu was added (if livewire/flux is installed)
Caches were cleared

Manual Configuration (If Needed)

Routes Not Injected Automatically

If the routes were not automatically injected into routes/web.php, manually add them:

Open routes/web.php
If you have configured your own starterkit, add the Volt import at the top of the file:
```
use Livewire\Volt\Volt;
```
Find the Route::middleware(['auth'])->group(function () { ... }); block
Add the routes from vendor/vormiaphp/ui-livewireflux-admin/src/stubs/reference/routes-to-add.php inside this block

Example:

<?php

use Livewire\Volt\Volt; // Add this if you have configured your own starterkit

Route::middleware(['auth'])->group(function () {
    // ... existing routes ...

    // Add admin routes here
    Route::group(['prefix' => 'admin'], function () {
        // Routes from routes-to-add.php
    });
});

Sidebar Menu Not Injected

If livewire/flux is not installed or the sidebar menu wasn't injected:

Open resources/views/components/layouts/app/sidebar.blade.php
Find the Platform navlist.group (the group containing the Dashboard menu item)
Add the code from vendor/vormiaphp/ui-livewireflux-admin/src/stubs/reference/sidebar-menu-to-add.blade.php after the closing </flux:navlist.group> tag of the Platform group

Example:

<flux:navlist.group :heading="__('Platform')" class="grid">
    <flux:navlist.item icon="home" :href="route('dashboard')" wire:navigate>
        {{ __('Dashboard') }}
    </flux:navlist.item>
</flux:navlist.group>

<!-- Add admin menu items here -->

Role Attachment Not Working

If laravel/fortify is not installed, manually attach roles to new users:

// In your user registration logic
$user = User::create([...]);
$user->roles()->attach(1); // 1 for admin

What You Get

1. AdminPanel Component

A reusable Blade component for consistent admin panel layouts:

<x-admin-panel
    header="Categories"
    desc="Manage your categories"
    :button="$createButton"
>
    <!-- Your content here -->
</x-admin-panel>

Location: app/View/Components/AdminPanel.php and resources/views/components/admin-panel.php

2. Admin Routes

Pre-configured routes for all admin sections:

Categories: /admin/categories, /admin/categories/create, /admin/categories/edit/{id}
Inheritance: /admin/inheritance, /admin/inheritance/create, /admin/inheritance/edit/{id}
Countries: /admin/countries, /admin/countries/create, /admin/countries/edit/{id}
Cities: /admin/cities, /admin/cities/create, /admin/cities/edit/{id}
Availability: /admin/availabilities, /admin/availabilities/create, /admin/availabilities/edit/{id}
Admins: /admin/admins, /admin/admins/create, /admin/admins/edit/{id}

All routes are protected by auth middleware.

3. Livewire Volt Components

Single-file components for each admin section:

resources/views/livewire/admin/admins/ - Admin user management
resources/views/livewire/admin/control/categories/ - Category management
resources/views/livewire/admin/control/inheritance/ - Inheritance management
resources/views/livewire/admin/control/locations/ - Location management (countries/cities)
resources/views/livewire/admin/control/availability/ - Availability management

Each section includes:

index.php / index.blade.php - List view
create.php / create.blade.php - Create form
edit.php / edit.blade.php - Edit form

4. Sidebar Menu Integration

When livewire/flux is installed, the sidebar automatically includes:

Countries navigation link
Cities navigation link
Availability navigation link
Inheritance navigation link
Admins navigation link (for super admins only)

5. Role Management

When laravel/fortify is installed, new users are automatically assigned the admin role (ID: 1) upon registration.

What to Be Aware Of

⚠️ Important Considerations

File Overwrites
- The installation process will copy files to your application
- If files already exist, you'll be prompted to overwrite them
- Always backup your files before updating
Middleware Requirements
- All admin routes require auth middleware
- Ensure your application has this middleware configured
Role IDs
- The package assumes role ID 1 is the admin role
- If your application uses different role IDs, you'll need to update:
  - app/Actions/Fortify/CreateNewUser.php (if using Fortify)
  - Any custom role attachment logic
Sidebar File Location
- The package expects the sidebar at: resources/views/components/layouts/app/sidebar.blade.php
- If your sidebar is in a different location, you'll need to manually add the menu items
Route Injection
- Routes are injected into routes/web.php
- The package looks for: Route::middleware(['auth'])->group(function () { ... });
- If this pattern doesn't exist, routes won't be injected automatically
Custom Modifications
- Any custom modifications to package files will be lost when updating
- Consider extending components instead of modifying them directly
- Backups are created during updates (stored in storage/app/ui-livewireflux-admin-backups/)
Dependencies
- The package requires vormiaphp/vormia - installation will fail without it
- livewire/flux and laravel/fortify are optional but recommended

Help, Update, and Uninstallation

Getting Help

Display comprehensive help information:

php artisan ui-livewireflux-admin:help

This command shows:

Available commands
Usage examples
Package features
Requirements
Troubleshooting tips

Checking Dependencies

Verify that all required and optional dependencies are installed:

php artisan ui-livewireflux-admin:check-dependencies

This command checks for:

✅ vormiaphp/vormia (required)
✅ livewire/volt (required)
⚠️ livewire/flux (optional)
⚠️ laravel/fortify (optional)

Updating the Package

Update all package files to the latest version:

php artisan ui-livewireflux-admin:update

What happens:

Creates a backup of existing files in storage/app/ui-livewireflux-admin-backups/
Replaces all package files with fresh copies
Clears application caches

Force update (skip confirmation):

php artisan ui-livewireflux-admin:update --force

⚠️ Warning: This will overwrite any custom modifications to package files. Always backup your changes first!

Uninstalling the Package

Remove all package files and configurations:

php artisan ui-livewireflux-admin:uninstall

What gets removed:

app/View/Components/AdminPanel.php
app/Actions/Fortify/CreateNewUser.php (if it was updated)
resources/views/components/admin-panel.php
resources/views/livewire/admin/ directory
Routes from routes/web.php
Sidebar menu items from sidebar.blade.php

Force uninstall (skip confirmation):

php artisan ui-livewireflux-admin:uninstall --force

⚠️ Warning: This action cannot be undone! Make sure you have backups before uninstalling.

Manual Route Removal:

If you need to manually remove routes, simply delete routes based on their names from routes/web.php:

admin.categories.index, admin.categories.create, admin.categories.edit
admin.inheritance.index, admin.inheritance.create, admin.inheritance.edit
admin.countries.index, admin.countries.create, admin.countries.edit
admin.cities.index, admin.cities.create, admin.cities.edit
admin.availabilities.index, admin.availabilities.create, admin.availabilities.edit
admin.admins.index, admin.admins.create, admin.admins.edit

After uninstallation:

Remove the package from composer.json:

composer remove vormiaphp/ui-livewireflux-admin

Run composer update to clean up dependencies

Package Structure

UILivewireFlux-Admin/
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       ├── InstallCommand.php
│   │       ├── UpdateCommand.php
│   │       ├── UninstallCommand.php
│   │       ├── HelpCommand.php
│   │       └── CheckDependenciesCommand.php
│   ├── stubs/                          # Files copied to Laravel app
│   │   ├── app/
│   │   │   ├── View/
│   │   │   │   └── Components/
│   │   │   │       └── AdminPanel.php
│   │   │   └── Actions/
│   │   │       └── Fortify/
│   │   │           └── CreateNewUser.php
│   │   └── resources/
│   │       └── views/
│   │           ├── components/
│   │           │   └── admin-panel.php
│   │           └── livewire/
│   │               └── admin/
│   │                   ├── admins/
│   │                   └── control/
│   │                       ├── availability/
│   │                       ├── categories/
│   │                       ├── inheritance/
│   │                       └── locations/
│   ├── UILivewireFlux.php
│   └── UILivewireFluxAdminServiceProvider.php
├── src/
│   └── stubs/
│       └── reference/
│           ├── routes-to-add.php       # Routes snippet
│           └── sidebar-menu-to-add.blade.php # Sidebar snippet
├── composer.json
└── README.md

Usage Examples

Using the AdminPanel Component

<x-admin-panel
    header="Manage Categories"
    desc="Create, edit, and delete categories"
    :button="
        <a href='{{ route('admin.categories.create') }}' class='btn btn-primary'>
            Create Category
        </a>
    "
>
    <!-- Your table or content here -->
    <table>
        <!-- ... -->
    </table>
</x-admin-panel>

Accessing Admin Routes

All routes are accessible via their named routes:

route('admin.categories.index')
route('admin.categories.create')
route('admin.categories.edit', ['id' => 1])

Troubleshooting

Installation Fails

Problem: Installation command fails with dependency errors.

Solution:

Ensure vormiaphp/vormia and livewire/volt are installed
Run php artisan ui-livewireflux-admin:check-dependencies to verify
Check that your PHP version is >= 8.2
Check that your Laravel version is >= 12.0

Routes Not Working

Problem: Admin routes return 404 or are not accessible.

Solution:

Verify routes were injected into routes/web.php
Check that the middleware group exists: Route::middleware(['auth'])->group(...)
Run php artisan route:clear and php artisan route:cache
Verify you're logged in and have the required permissions

Sidebar Menu Not Appearing

Problem: Sidebar menu items are not visible.

Solution:

Check if livewire/flux is installed: composer show livewire/flux
Verify the sidebar file exists at: resources/views/components/layouts/app/sidebar.blade.php
Manually add the menu code from vendor/vormiaphp/ui-livewireflux-admin/src/stubs/reference/sidebar-menu-to-add.blade.php if needed
Clear view cache: php artisan view:clear

Role Attachment Not Working

Problem: New users are not getting the admin role.

Solution:

Check if laravel/fortify is installed
Verify app/Actions/Fortify/CreateNewUser.php exists and was updated
Check that the role ID 1 exists in your database
Manually add role attachment if needed

License

MIT

Support

For issues, questions, or contributions, please visit:

GitHub: https://github.com/vormiaphp/ui-livewireflux-admin
Packagist: https://packagist.org/packages/vormiaphp/ui-livewireflux-admin

vormiaphp / ui-livewireflux-admin

Maintainers

Details

README

What is This Package?

Prerequisites

Required Packages

Optional Packages

livewire/flux

laravel/fortify

Installation Process

Step 1: Install the Package

Step 2: Run the Installation Command

Step 3: Verify Installation

Manual Configuration (If Needed)

Routes Not Injected Automatically

Sidebar Menu Not Injected

Role Attachment Not Working

What You Get

1. AdminPanel Component

2. Admin Routes

3. Livewire Volt Components

4. Sidebar Menu Integration

5. Role Management

What to Be Aware Of

⚠️ Important Considerations

Help, Update, and Uninstallation

Getting Help

Checking Dependencies

Updating the Package

Uninstalling the Package

Package Structure

Usage Examples

Using the AdminPanel Component

Accessing Admin Routes

Troubleshooting

Installation Fails

Routes Not Working

Sidebar Menu Not Appearing

Role Attachment Not Working

License

Support