README

A comprehensive, enterprise-grade theme management system for Laravel Filament applications.

Built to seamlessly integrate with qirolab/laravel-themer, this package provides a sophisticated admin interface for managing, installing, previewing, and switching themes with professional-grade security and performance optimization.

🚀 Key Features

Theme Management

• Multi-source Installation - Deploy themes from ZIP files, GitHub repositories, or local directories
• Advanced Cloning System - Duplicate and customize existing themes with intelligent inheritance
• One-Click Activation - Seamlessly switch between themes without downtime
• Safe Deletion - Remove themes with built-in protection for critical system themes
• Live Preview - Test themes in isolation without affecting other users

Security & Validation

• Structure Validation - Comprehensive theme integrity checking
• File Type Restrictions - Configurable security policies for theme uploads
• Protected Themes - Safeguard critical themes from accidental deletion
• Compatibility Checking - Automatic PHP/Laravel version validation
• Malicious Code Scanning - Optional security scanning for theme files

Developer Experience

• Artisan CLI Integration - Full command-line theme management
• Comprehensive API - Programmatic theme operations
• Event System - Custom integrations and workflows
• Multi-language Support - Extensive internationalization
• Cache Optimization - Performance-tuned with intelligent caching

Analytics & Monitoring

• Usage Analytics - Detailed theme performance metrics
• Health Monitoring - Real-time validation status tracking
• Statistics Dashboard - Comprehensive overview widgets
• Asset Compilation - Build status and asset management

📋 System Requirements

⚡ Quick Installation

1. Install Package

composer require alizharb/filament-themes-manager

2. Publish Configuration

php artisan vendor:publish --tag=filament-themes-manager-config

3. Register Plugin

Add to your Filament panel in app/Providers/Filament/AdminPanelProvider.php:

use Alizharb\FilamentThemesManager\FilamentThemesManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentThemesManagerPlugin::make(),
        ]);
}

4. Enable Preview System (Optional)

Add middleware to bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Alizharb\FilamentThemesManager\Http\Middleware\ThemePreviewMiddleware::class,
    ]);
})

🎯 Usage Guide

Admin Interface

Access the theme management interface at System → Theme Manager in your Filament admin panel.

Core Operations

Bulk Operations

• Multi-select themes using checkboxes
• Bulk deletion of compatible themes
• Configuration export for backup and migration

Command Line Interface

GitHub Installation

php artisan theme:install username/repository --type=github --activate

ZIP Installation

php artisan theme:install /path/to/theme.zip --type=zip

Theme Cloning

php artisan theme:clone default "Custom Default" --slug=custom-default --activate

🏗️ Theme Structure

Required Directory Layout

themes/my-theme/
├── theme.json          # Theme manifest (required)
├── views/              # Blade templates
│   ├── components/     # Reusable components
│   └── layouts/        # Page layouts
├── css/
│   └── app.css        # Stylesheets
├── js/
│   └── app.js         # JavaScript assets
├── vite.config.js     # Build configuration
└── screenshot.png     # Preview image

Theme Manifest (theme.json)

{
  "name": "Professional Theme",
  "slug": "professional-theme",
  "version": "1.0.0",
  "description": "A professional theme for Laravel applications",
  "author": "Your Name",
  "author_email": "contact@example.com",
  "homepage": "https://example.com",
  "screenshot": "screenshot.png",
  "parent": null,
  "requirements": {
    "php": ">=8.3",
    "laravel": ">=12.0"
  },
  "assets": ["css/app.css", "js/app.js"],
  "supports": ["responsive", "dark-mode"],
  "license": "MIT"
}

⚙️ Configuration

Theme Discovery

'discovery' => [
    'paths' => [
        'themes' => base_path('themes'),
        'resources' => resource_path('themes'),
    ],
    'cache_duration' => 3600,
    'auto_discover' => true,
],

Security Configuration

'security' => [
    'validate_theme_structure' => true,
    'scan_malicious_code' => true,
    'protected_themes' => ['default'],
    'allowed_file_types' => [
        'php', 'blade.php', 'css', 'scss', 'js', 'vue', 'json'
    ],
],

Preview System

'preview' => [
    'enabled' => true,
    'route_prefix' => 'theme-preview',
    'session_duration' => 3600,
    'cache_screenshots' => true,
],

Dashboard Widgets

'widgets' => [
    'enabled' => true,
    'page' => true,      // Theme Manager page
    'dashboard' => true, // Main dashboard
],

🎨 Live Preview System

Capabilities

• Session Isolation - Preview affects only current user
• Professional UI - Elegant banner with intuitive controls
• One-Click Activation - Seamless transition to permanent theme
• Auto-Expiration - Automatic fallback to original theme
• Keyboard Shortcuts - Ctrl+H to toggle banner visibility

Preview Routes

🔧 API Reference

Theme Manager Service

use Alizharb\FilamentThemesManager\Services\ThemeManagerService;

$service = app(ThemeManagerService::class);

// Theme operations
$themes = $service->getAllThemes();
$service->setActiveTheme('theme-slug');
$service->installThemeFromGitHub('username/repository');
$service->cloneTheme('source-slug', 'new-slug', 'New Theme Name');

// Analytics
$stats = $service->getThemeStats();

Theme Model

use Alizharb\FilamentThemesManager\Models\Theme;

// Queries
$themes = Theme::all();
$activeThemes = Theme::active()->get();
$validThemes = Theme::valid()->get();
$theme = Theme::bySlug('theme-slug')->first();

// Statistics
$totalCount = Theme::count();
$activeCount = Theme::getActiveCount();
$validCount = Theme::getValidCount();

🔍 Troubleshooting

Common Issues

Themes Not Appearing

• Check Permissions: Verify themes directory is readable
• Validate JSON: Ensure theme.json files contain valid JSON
• Clear Cache: Run php artisan cache:clear

Preview System Issues

• Middleware Registration: Confirm middleware is properly registered
• Route Accessibility: Verify preview routes are accessible
• Session Configuration: Check session driver and configuration

Asset Loading Problems

• Vite Configuration: Verify theme's Vite setup is correct
• Asset Paths: Ensure paths in theme.json are accurate
• Build Process: Run npm run build for production assets

Debug Configuration

'debug' => env('THEME_DEBUG', false),

Performance Optimization

• Enable theme caching in production environments
• Configure appropriate cache durations
• Utilize asset compilation for faster loading

🧪 Development

Contributing Guidelines

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Testing Suite

composer test              # Run test suite
vendor/bin/pest            # Run Pest tests directly
vendor/bin/pest --coverage # Generate coverage report
vendor/bin/phpstan analyse # Static analysis

Code Quality

vendor/bin/pint           # Fix code style
vendor/bin/rector process # Code modernization

📜 License

This package is open-sourced software licensed under the MIT License. See LICENSE.md for details.

🏆 Credits

Core Contributors

• Ali Harb - Lead Developer & Maintainer

Dependencies

• Filament - Admin panel framework
• qirolab/laravel-themer - Core theming engine
• Laravel - PHP framework foundation

💝 Support the Project

Your support helps maintain and improve this package:

• ⭐ Star the repository
• 🐛 Report bugs and issues
• 💡 Suggest new features
• 📚 Improve documentation
• 💰 Sponsor development

Built with ❤️ by Ali Harb

Making Laravel theming professional and accessible