README

A modular Laravel package that adds Ladwire components to fresh Laravel projects with dashboard, user management, and settings functionality, built with modern Flux UI components.

Features

Modular Architecture: Install only the modules you need
Dashboard: Statistics and recent activity overview
User Management: CRUD operations for users with search and pagination
Settings: Configurable application settings
Ladwire Powered: All components use Ladwire for reactive UI
Flux UI: Modern, accessible component library
Easy Integration: Simple installation and configuration

Requirements

PHP 8.2+
Laravel 11.0+ / 12.0+
Livewire 3.0+ / 4.0+
Flux UI 1.0+ / 2.0+

Installation

For Package Development

If you're developing this package or want to use it in an existing project:

# Install latest version (v1.1.0+ with starter kit structure)
composer require ladbu/laravel-ladwire-module

# Install specific version
composer require ladbu/laravel-ladwire-module:1.1.0

# Install older version (original structure)
composer require ladbu/laravel-ladwire-module:1.0.8

Version Information

v1.1.0+ - Current architecture with local modules and clean installer
v1.0.8 - Original Ladwire structure

For Fresh Laravel Projects

For fresh Laravel projects, you can use the installer command to set up everything quickly:

# Install the package in your fresh project
composer require ladbu/laravel-ladwire-module

# Install specific modules
php artisan ladwire:install-clean --dashboard
php artisan ladwire:install-clean --user-management
php artisan ladwire:install-clean --settings

# Install all modules
php artisan ladwire:install-clean

Post-Installation Steps

After running the installer command:

Install and configure Flux UI (if not already installed):

php artisan flux:install

Publish views (optional, if you want to customize them):

php artisan vendor:publish --tag="views" --provider="Ladbu\\LaravelLadwireModule\\LaravelLadwireModuleServiceProvider"

For Fresh Projects - Quick Start

The installer command creates files following the Laravel Livewire starter kit structure:

Generated File Structure:

app/
├── Http/
│   └── Controllers/
│       ├── DashboardController.php
│       └── SettingsController.php
├── Livewire/
│   └── Actions/
│       └── Logout.php
└── Providers/
    └── LaravelLadwireModuleServiceProvider.php

resources/
└── views/
    ├── layouts/
    │   └── app.blade.php
    ├── pages/
    │   ├── auth/
    │   │   ├── login.blade.php
    │   │   ├── register.blade.php
    │   │   ├── forgot-password.blade.php
    │   │   ├── reset-password.blade.php
    │   │   ├── verify-email.blade.php
    │   │   ├── confirm-password.blade.php
    │   │   └── two-factor-challenge.blade.php
    │   └── settings/
    │       ├── layout.blade.php
    │       ├── ⚡profile.blade.php
    │       ├── ⚡password.blade.php
    │       ├── ⚡appearance.blade.php
    │       ├── ⚡two-factor.blade.php
    │       └── ⚡delete-user-form.blade.php
    ├── components/
    ├── ladwire/
    │   ├── dashboard.blade.php
    │   ├── user-management.blade.php
    │   └── settings.blade.php
    ├── flux/
    └── partials/

routes/
├── web.php
└── settings.php

Package Templates (source):
src/
├── Templates/
│   ├── Controllers/
│   │   ├── DashboardController.php
│   │   ├── SettingsController.php
│   │   └── UserManagementController.php
│   └── Views/
│       ├── dashboard.blade.php
│       ├── settings.blade.php
│       └── user-management.blade.php
└── Console/
    └── Commands/
        └── InstallLadwireModuleClean.php

Example usage in your fresh project:

// routes/web.php
Route::get('/', function () {
    return view('welcome');
})->name('home');

Route::view('dashboard', 'dashboard')
    ->middleware(['auth', 'verified'])
    ->name('dashboard');

Route::get('/dashboard', DashboardController::class)->name('dashboard');

require __DIR__.'/settings.php';

// routes/settings.php
Route::middleware(['auth'])->group(function () {
    Route::redirect('settings', 'settings/profile');
    Route::livewire('settings/profile', 'pages::settings.profile')->name('profile.edit');
});

Route::middleware(['auth', 'verified'])->group(function () {
    Route::livewire('settings/password', 'pages::settings.password')->name('user-password.edit');
    Route::livewire('settings/appearance', 'pages::settings.appearance')->name('appearance.edit');
    Route::livewire('settings/two-factor', 'pages::settings.two-factor')
        ->middleware([/* two-factor middleware */])
        ->name('two-factor.show');
});

{{-- resources/views/ladwire/dashboard.blade.php --}}
<x-layouts::app :title="__('Dashboard')">
    <flux:main>
        <livewire:laravel-ladwire-dashboard::dashboard />
    </flux:main>
</x-layouts::app>

Usage

Once installed, you can access the modules at the following routes:

Authentication Routes (Generated by Laravel Fortify)

/login - User login
/register - User registration
/forgot-password - Password reset request
/reset-password - Password reset form
/email/verify - Email verification
/password/confirm - Password confirmation

Dashboard Module

/dashboard - Main dashboard (requires auth & verification)
Dashboard shows statistics and recent activity

Settings Module

/settings/profile - Profile settings (requires auth)
/settings/password - Password change (requires auth & verification)
/settings/appearance - Appearance settings (requires auth & verification)
/settings/two-factor - Two-factor authentication (requires auth & verification)

Ladwire Module Routes

/module-dashboard - Ladwire dashboard component
/module-users - Ladwire user management
/module-settings - Ladwire settings component

Using Components in Your Views

You can use the Livewire components following the inline component pattern (⚡ prefix):

<!-- Settings Profile Component (Inline) -->
<flux:main>
    @livewire('pages::settings.profile')
</flux:main>

<!-- Settings Password Component (Inline) -->
<flux:main>
    @livewire('pages::settings.password')
</flux:main>

<!-- Ladwire Dashboard Component -->
<flux:main>
    <livewire:laravel-ladwire-dashboard::dashboard />
</flux:main>

<!-- Ladwire User Management Component -->
<flux:main>
    <livewire:laravel-ladwire-user-management::user-management />
</flux:main>

<!-- Ladwire Settings Component -->
<flux:main>
    <livewire:laravel-ladwire-settings::settings />
</flux:main>

Inline Component Structure

The starter kit uses inline Livewire components with the ⚡ prefix pattern:

// Example: resources/views/pages/settings/⚡profile.blade.php
<?php

use App\Concerns\ProfileValidationRules;
use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Livewire\Component;

new class extends Component {
    use ProfileValidationRules;

    public string $name = '';
    public string $email = '';

    public function mount(): void
    {
        $this->name = Auth::user()->name;
        $this->email = Auth::user()->email;
    }

    public function updateProfileInformation(): void
    {
        $user = Auth::user();
        $validated = $this->validate($this->profileRules($user->id));
        
        $user->fill($validated);
        
        if ($user->isDirty('email')) {
            $user->email_verified_at = null;
        }
        
        $user->save();
        
        $this->dispatch('profile-updated', name: $user->name);
    }
};
?>

{{-- HTML/Blade template part --}}
<flux:heading>Profile Information</flux:heading>
<flux:form>
    <!-- Form fields here -->
</flux:form>

Module Discovery

The main package automatically discovers and registers available modules from the local modules/ directory. The LaravelLadwireModuleServiceProvider checks for the presence of service providers:

Ladbu\LaravelLadwireDashboard\DashboardServiceProvider
Ladbu\LaravelLadwireUserManagement\UserManagementServiceProvider
Ladbu\LaravelLadwireSettings\SettingsServiceProvider

The installer command copies templates from src/Templates/ to your Laravel application and registers the routes automatically.

Ladwire Components

The package uses Ladwire with Flux UI components for a modern, accessible interface. Some key components used:

<flux:card> - Container components
<flux:table> - Data tables with built-in responsiveness
<flux:modal> - Modal dialogs
<flux:form> - Form handling with validation
<flux:button> - Button components with variants
<flux:icon> - Icon components
<flux:badge> - Status indicators
<flux:avatar> - User avatars
<flux:checkbox> - Toggle switches
<flux:dropdown> - Dropdown menus
<flux:navbar> - Navigation components

Modules

Authentication Module (Built-in with Laravel Fortify)

Complete authentication system with:

User registration and login
Password reset functionality
Email verification
Two-factor authentication
Session management
Password confirmation for sensitive actions

Files Generated:

resources/views/pages/auth/ - Authentication views
app/Livewire/Actions/Logout.php - Logout action
Routes handled by Laravel Fortify

Settings Module

User profile and application settings with:

Profile Settings: Name and email management
Password Settings: Secure password change
Appearance Settings: UI customization options
Two-Factor Authentication: 2FA setup and management
Account Deletion: Safe account removal

Files Generated:

resources/views/pages/settings/⚡profile.blade.php - Profile management
resources/views/pages/settings/⚡password.blade.php - Password change
resources/views/pages/settings/⚡appearance.blade.php - Appearance settings
resources/views/pages/settings/⚡two-factor.blade.php - 2FA management
resources/views/pages/settings/⚡delete-user-form.blade.php - Account deletion
resources/views/pages/settings/layout.blade.php - Settings layout
routes/settings.php - Settings routes

Ladwire Dashboard Module

Comprehensive admin dashboard with:

Statistics cards (users, posts, activity)
Recent activity timeline
Responsive grid layout
Real-time updates with Livewire
Flux UI components

Module Location: modules/dashboard/ Files Generated:

resources/views/ladwire/dashboard.blade.php - Dashboard component
app/Http/Controllers/DashboardController.php - Dashboard controller

Ladwire User Management Module

Complete user administration with:

User listing with search and pagination
Create, edit, and delete users
Role management
Bulk operations support
Modal-based forms

Module Location: modules/user-management/ Files Generated:

resources/views/ladwire/user-management.blade.php - User management component

Ladwire Settings Module

Application configuration management:

General settings (site name, description)
Email configuration
Feature toggles
Form validation
Settings persistence

Module Location: modules/settings/ Files Generated:

resources/views/ladwire/settings.blade.php - Settings component

Testing

Running Tests

The package includes a comprehensive test suite to ensure all modules work correctly:

# Run all tests
composer test

# Run specific test suites
composer test --testsuite=Feature
composer test --testsuite=Unit

# Run with coverage
composer test --coverage-html

Test Structure

``bash tests/ ├── Feature/ │ ├── DashboardTest.php │ ├── UserManagementTest.php │ └── SettingsTest.php ├── Unit/ ├── CreatesApplication.php ├── TestCase.php └── laravel-app-example/ # Example Laravel app for integration testing ├── .env.example ├── composer.json ├── database/ │ └── migrations/ ├── app/Models/ ├── resources/views/ladwire/ └── routes/web.php


### Integration Testing

For comprehensive testing, use the included example Laravel app:

```bash
# Copy the example app
cp -r tests/laravel-app-example/* .

# Install dependencies
cd tests/laravel-app-example && composer install

# Run tests
composer test

Test Coverage

The package is configured for test coverage reporting. Coverage reports will be generated in:

build/logs/clover.xml (for CI/CD)
build/logs/coverage.html (for visual inspection)

Continuous Integration

Example GitHub Actions workflow:

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    - uses: shivammathur/composer-dependency-action@v1
    - name: Install Dependencies
      run: composer install --prefer-dist --no-progress --no-suggest --optimize-autoloader --no-scripts
    
    - name: Run Tests
      run: vendor/bin/phpunit --coverage-clover --coverage-html

Requirements

PHP 8.2+
Laravel 11.0+ / 12.0+
Livewire 3.0+ / 4.0+
Flux UI 1.0+ / 2.0+

Environment Variables

You can configure modules using environment variables:

# Enable/disable individual modules
LARAVEL_LADWIRE_DASHBOARD_ENABLED=true
LARAVEL_LADWIRE_USER_MANAGEMENT_ENABLED=true
LARAVEL_LADWIRE_SETTINGS_ENABLED=true

# Custom route prefixes
LARAVEL_LADWIRE_DASHBOARD_ROUTE_PREFIX=admin
LARAVEL_LADWIRE_USER_MANAGEMENT_ROUTE_PREFIX=admin
LARAVEL_LADWIRE_SETTINGS_ROUTE_PREFIX=admin

Customization

Overriding Views

Publish the views to customize them:

php artisan vendor:publish --tag="views" --provider="Ladbu\\LaravelLadwireModule\\LaravelLadwireModuleServiceProvider"

The views will be published to resources/views/vendor/laravel-ladwire-module/.

Extending Components

You can extend the package components in your application:

<?php

namespace App\Http\Livewire;

use Ladbu\LaravelLadwireModule\Http\Livewire\Dashboard as BaseDashboard;

class CustomDashboard extends BaseDashboard
{
    // Override methods or add new functionality
}

Development

Installation for Development

Clone this repository
Install dependencies:

composer install

Run tests:

composer test

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This package is open-sourced software licensed under the MIT license.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

Changelog

v1.1.0+ - Current Architecture

NEW: Local module structure in modules/ directory
NEW: Clean installer command ladwire:install-clean
NEW: Template system in src/Templates/
UPDATED: Requirements - PHP 8.2+, Laravel 11.0+/12.0+, Livewire 3.0+/4.0+, Flux 1.0+/2.0+
NEW: Service provider-based module discovery
NEW: Comprehensive documentation updates
NEW: Proper view structure with layouts.app

v1.0.8 - Original Structure

Initial release with original Ladwire structure
Laravel 11.0+ / 12.0+, Livewire 3.0+, Flux 1.0+
Traditional component pattern only

Roadmap

File management module
Analytics module
Notification system module
Blog module
E-commerce module
API documentation module

ladbu / laravel-ladwire-module

Maintainers

Details

README

Features

Requirements

Installation

For Package Development

Version Information

For Fresh Laravel Projects

Post-Installation Steps

For Fresh Projects - Quick Start

Generated File Structure:

Example usage in your fresh project:

Usage

Authentication Routes (Generated by Laravel Fortify)

Dashboard Module

Settings Module

Ladwire Module Routes

Using Components in Your Views

Inline Component Structure

Module Discovery

Ladwire Components

Modules

Authentication Module (Built-in with Laravel Fortify)

Settings Module

Ladwire Dashboard Module

Ladwire User Management Module

Ladwire Settings Module

Testing

Running Tests

Test Structure

Test Coverage

Continuous Integration

Requirements

Environment Variables

Customization

Overriding Views

Extending Components

Development

Installation for Development

Contributing

License

Support

Changelog

v1.1.0+ - Current Architecture

v1.0.8 - Original Structure

Roadmap