Module Manager

• 📖 Table of Contents
• ✨ Features
  • 🎯 Core Module Management
  • 🚀 Enterprise Features (v2.0)
    • 🔗 Dependency Management
    • 🔄 Update System
    • 💾 Backup & Restore
    • 🏥 Health Monitoring
    • 📝 Audit Logging
    • 🐙 GitHub Integration
• 📋 Requirements
• ⚡ Installation
  • Step 1: Install via Composer
  • Step 2: Register the Plugin
  • Step 3: Publish Assets (Optional)
• 🎯 Quick Start
  • Access the Module Manager
  • Install Your First Module
  • Enable/Disable Modules
• 🎯 Core Features
  • 📦 Module Installation
    • ZIP Upload Installation
    • Multi-Module Package Installation
    • GitHub Repository Installation
  • 📊 Dashboard Widget
• 🚀 Enterprise Features
  • 1. 🔗 Module Dependencies Management
    • Define Dependencies
    • Version Constraints
    • Features
    • Usage Example
  • 2. 🔄 Module Update System
    • Configuration
    • Setup Module for Updates
    • Features
    • Usage Example
  • 3. 💾 Backup & Restore
    • Configuration
    • Features
    • Storage
    • Usage Example
  • 4. 🏥 Health Monitoring
    • Configuration
    • Health Checks Performed
    • Health Scoring
    • Storage
    • Usage Example
  • 5. 📝 Audit Logging
    • Logged Information
    • Storage
    • Usage Example
  • 6. 🐙 Enhanced GitHub Integration
    • Configuration
    • Features
    • Setup
    • Usage Example
• ⚙️ Configuration
  • Navigation Settings
  • Upload Settings
  • Widget Settings
  • Permissions
• 💡 Usage Examples
  • Programmatic Module Management
  • Working with Dependencies
  • Health Monitoring
• 🌍 Multi-Language Support
  • Customize Translations
• 🤝 Contributing
  • Development Setup
  • Testing
• 💖 Sponsor This Project
• 🐛 Issues & Support
• 📄 License
• 🙏 Acknowledgments

Enterprise-grade module management for Filament v4 & v5 admin panels
Complete lifecycle management with dependencies, updates, backups, and health monitoring
Built on Nwidart/laravel-modules

#📖 Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Core Features
• Enterprise Features
• Configuration
• Usage Examples
• Contributing
• License

#✨ Features

#🎯 Core Module Management

• 📦 Full CRUD Operations - View, install, enable, disable, and uninstall modules
• 📤 Multiple Installation Methods - ZIP upload, GitHub repository, or local path
• 🏷️ Multi-Module Packages - Install multiple modules from a single package
• 📊 Dashboard Widget - Real-time statistics and module overview
• 🌍 Multi-Language Support - 20+ languages included
• ⚙️ Highly Configurable - Customize navigation, uploads, and behavior

#🚀 Enterprise Features (v2.0)

#📋 Requirements

Requirement	Version	Status
	8.3+	✅
	10+	✅
	v4/v5	✅

Dependencies:

• Nwidart Laravel Modules - Module foundation
• Spatie Laravel Data - Type-safe DTOs

#⚡ Installation

#Step 1: Install via Composer

composer require alizharb/filament-module-manager

#Step 2: Register the Plugin

Add to your AdminPanelProvider:

use Alizharb\FilamentModuleManager\FilamentModuleManagerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentModuleManagerPlugin::make());
}

#Step 3: Publish Assets (Optional)

# Publish configuration
php artisan vendor:publish --tag="filament-module-manager-config"

# Publish translations
php artisan vendor:publish --tag="filament-module-manager-translations"

#🎯 Quick Start

#Access the Module Manager

Navigate to Module Manager in your Filament admin sidebar.

#Install Your First Module

Option 1: Upload ZIP

1. Prepare module as ZIP with module.json in root
2. Click "Upload Module" button
3. Select ZIP file (max 20MB by default)
4. Module installs and appears in list

Option 2: Install from GitHub

1. Add repository to module's module.json:

   {
     "name": "Blog",
     "repository": "username/blog-module"
   }
   

2. Use GitHub installation feature
3. Module downloads and installs automatically

#Enable/Disable Modules

• Toggle module status with one click
• Automatic dependency validation
• Cache clearing after changes

#🎯 Core Features

#📦 Module Installation

#ZIP Upload Installation

Upload modules as ZIP files with automatic validation:

MyModule.zip
└── MyModule/
    ├── module.json      # Required
    ├── composer.json    # Optional
    ├── Config/
    ├── Http/
    └── resources/

Features:

• ✅ Automatic module.json validation
• ✅ Folder name correction
• ✅ Metadata extraction
• ✅ Duplicate detection
• ✅ Size limit enforcement

#Multi-Module Package Installation

Install multiple modules from a single package:

// package.json in ZIP root
{
  "name": "my-module-collection",
  "version": "1.0.0",
  "modules": ["Modules/Blog", "Modules/Shop", "Modules/User"]
}

Upload the package ZIP and all modules install automatically.

#GitHub Repository Installation

Install directly from GitHub repositories:

// module.json
{
  "name": "Blog",
  "version": "1.0.0",
  "repository": "username/blog-module"
}

Features:

• ✅ Branch fallback (main → master)
• ✅ OAuth token support for private repos
• ✅ Automatic extraction and installation

#📊 Dashboard Widget

Real-time module statistics:

• 🟢 Active Modules - Currently enabled
• 🔴 Disabled Modules - Installed but inactive
• 📈 Total Modules - All installed modules

Configure widget placement:

'widget' => [
    'enabled' => true,
    'show_on_dashboard' => true,
    'show_on_module_page' => true,
],

#🚀 Enterprise Features

#1. 🔗 Module Dependencies Management

Automatically manage module dependencies with validation and conflict prevention.

#Define Dependencies

In your module.json:

{
  "name": "Blog",
  "version": "1.0.0",
  "requires": {
    "User": "^1.0",
    "Media": "~2.0",
    "Core": "*"
  }
}

#Version Constraints

#Features

• ✅ Automatic Validation - Checks dependencies before install/enable
• ✅ Circular Detection - Prevents circular dependency loops
• ✅ Dependent Protection - Can't disable modules with active dependents
• ✅ Dependency Tree - Visual representation of relationships
• ✅ Installation Order - Topological sorting for correct order

#Usage Example

use Alizharb\FilamentModuleManager\Services\ModuleDependencyService;

$service = app(ModuleDependencyService::class);

// Validate dependencies
$service->validateDependencies('Blog');

// Get dependency tree
$tree = $service->getDependencyTree('Blog');

// Check if can disable
$canDisable = $service->canDisable('User'); // false if Blog depends on it

// Get modules that depend on this one
$dependents = $service->getDependents('User'); // ['Blog', 'Shop']

#2. 🔄 Module Update System

Check and apply updates from GitHub releases with automatic backups.

#Configuration

'updates' => [
    'enabled' => true,
    'auto_check' => false,
    'check_frequency' => 24, // hours
],

#Setup Module for Updates

Add repository to module.json:

{
  "name": "Blog",
  "version": "1.0.0",
  "repository": "username/blog-module"
}

#Features

• ✅ Version Comparison - Automatic detection of newer versions
• ✅ Changelog Display - Shows release notes before updating
• ✅ Automatic Backup - Creates backup before applying update
• ✅ Tag/Release Support - Install from specific versions
• ✅ Batch Updates - Check all modules at once

#Usage Example

use Alizharb\FilamentModuleManager\Services\ModuleUpdateService;

$service = app(ModuleUpdateService::class);

// Check for update
$updateData = $service->checkForUpdate('Blog');

if ($updateData->updateAvailable) {
    echo "Update available: {$updateData->latestVersion}";
    echo "Changelog: {$updateData->changelog}";

    // Apply update
    $service->updateModule('Blog');
}

// Batch check all modules
$updates = $service->batchCheckUpdates();

#3. 💾 Backup & Restore

Automatic backups before critical operations with one-click restore.

#Configuration

'backups' => [
    'enabled' => true,
    'backup_before_update' => true,
    'backup_before_uninstall' => true,
    'retention_days' => 30,
],

#Features

• ✅ Automatic Backups - Before updates and uninstalls
• ✅ ZIP Compression - Efficient storage
• ✅ Metadata Tracking - Size, date, reason, user
• ✅ One-Click Restore - Restore from backup instantly
• ✅ Retention Management - Auto-cleanup old backups

#Storage

• Backups: storage/app/module-backups/*.zip
• Metadata: storage/app/module-backups/backups.json

#Usage Example

use Alizharb\FilamentModuleManager\Services\ModuleBackupService;

$service = app(ModuleBackupService::class);

// Create backup
$backup = $service->createBackup('Blog', 'Manual backup');

// List backups
$backups = $service->getBackups('Blog');

// Restore from backup
$service->restoreBackup($backup->id);

// Delete old backups
$service->deleteBackup($backup->id);

#4. 🏥 Health Monitoring

Automated health checks with scoring and status categorization.

#Configuration

'health_checks' => [
    'enabled' => true,
    'auto_check' => true, // After install/update
],

#Health Checks Performed

#Health Scoring

• 🟢 Healthy (80-100) - All checks passed
• 🟡 Warning (50-79) - Some checks failed
• 🔴 Critical (0-49) - Multiple failures

#Storage

• Health Data: storage/app/module-manager/health-checks.json

#Usage Example

use Alizharb\FilamentModuleManager\Services\ModuleHealthService;

$service = app(ModuleHealthService::class);

// Check module health
$health = $service->checkHealth('Blog');

echo "Status: {$health->status}"; // healthy, warning, critical
echo "Score: {$health->score}/100";
echo "Message: {$health->message}";

// Individual checks
foreach ($health->checks as $check => $passed) {
    echo "{$check}: " . ($passed ? '✅' : '❌');
}

#5. 📝 Audit Logging

Complete audit trail of all module operations for compliance and debugging.

#Logged Information

• Action - install, uninstall, enable, disable, update, backup, restore
• Module Name - Which module was affected
• User - ID and name of user who performed action
• IP Address - Request IP
• User Agent - Browser/client information
• Timestamp - When action occurred
• Status - Success or failure
• Error Message - If action failed
• Metadata - Additional context

#Storage

• Audit Logs: storage/app/module-manager/audit-logs.json
• Retention: Last 1000 entries

#Usage Example

use Alizharb\FilamentModuleManager\Services\AuditLogService;

$service = app(AuditLogService::class);

// Log an action
$service->log(
    action: 'install',
    moduleName: 'Blog',
    success: true,
    metadata: ['version' => '1.0.0']
);

// Logs are automatically created for:
// - Module install/uninstall
// - Module enable/disable
// - Module updates
// - Backup creation/restoration

#6. 🐙 Enhanced GitHub Integration

Advanced GitHub API integration with release management and OAuth support.

#Configuration

'github' => [
    'token' => env('GITHUB_TOKEN'), // Optional, increases rate limits
    'default_branch' => 'main',
    'fallback_branch' => 'master',
],

#Features

• ✅ Release Management - Fetch and install from releases
• ✅ Tag Support - Install specific versions
• ✅ Changelog Retrieval - Display release notes
• ✅ OAuth Token - Support for private repositories
• ✅ Rate Limit Management - Handles API limits gracefully
• ✅ Branch Fallback - Tries main, falls back to master

#Setup

1. Add GitHub Token (Optional)

   # .env
   GITHUB_TOKEN=ghp_your_token_here
   

2. Add Repository to module.json

   {
     "name": "Blog",
     "version": "1.0.0",
     "repository": "username/blog-module"
   }
   

#Usage Example

use Alizharb\FilamentModuleManager\Services\GitHubService;

$service = app(GitHubService::class);

// Get latest release
$release = $service->getLatestRelease('username/blog-module');

// Get all releases
$releases = $service->getAllReleases('username/blog-module');

// Get specific release
$release = $service->getReleaseByTag('username/blog-module', 'v1.0.0');

// Download release
$zipPath = $service->downloadRelease('username/blog-module', 'v1.0.0');

// Get changelog
$changelog = $service->getChangelog('username/blog-module', 'v1.0.0');

#⚙️ Configuration

#Navigation Settings

'navigation' => [
    'register' => true,
    'sort' => 100,
    'icon' => 'heroicon-o-code-bracket',
    'group' => 'System',
    'label' => 'Module Manager',
],

#Upload Settings

'upload' => [
    'disk' => 'public',
    'temp_directory' => 'temp/modules',
    'max_size' => 20 * 1024 * 1024, // 20MB
],

#Widget Settings

'widget' => [
    'enabled' => true,
    'show_on_dashboard' => true,
    'show_on_module_page' => true,
],

#Permissions

'permissions' => [
    'enabled' => true,
    'prefix' => 'module',
    'actions' => [
        'view' => 'module.view',
        'install' => 'module.install',
        'uninstall' => 'module.uninstall',
        'enable' => 'module.enable',
        'disable' => 'module.disable',
        'update' => 'module.update',
    ],
],

#💡 Usage Examples

#Programmatic Module Management

use Alizharb\FilamentModuleManager\Facades\ModuleManager;

// Enable a module
ModuleManager::enable('Blog');

// Disable a module
ModuleManager::disable('Blog');

// Get module data
$module = ModuleManager::findModule('Blog');

// Install from ZIP
$result = ModuleManager::installModulesFromZip('/path/to/module.zip');

// Install from GitHub
$result = ModuleManager::installModuleFromGitHub('Blog');

// Uninstall module
$result = ModuleManager::uninstallModule('Blog');

#Working with Dependencies

use Alizharb\FilamentModuleManager\Services\ModuleDependencyService;

$service = app(ModuleDependencyService::class);

// Get all dependencies
$dependencies = $service->getModuleDependencies('Blog');

// Get dependency tree
$tree = $service->getDependencyTree('Blog');

// Resolve installation order
$order = $service->resolveDependencies(['Blog', 'Shop', 'User']);

#Health Monitoring

use Alizharb\FilamentModuleManager\Services\ModuleHealthService;

$service = app(ModuleHealthService::class);

$health = $service->checkHealth('Blog');

if ($health->isCritical()) {
    // Handle critical issues
    Log::error("Module Blog has critical issues: {$health->message}");
}

#🌍 Multi-Language Support

The package includes translations for 20+ languages:

• English, Arabic, Spanish, French, German
• Italian, Portuguese, Russian, Chinese, Japanese
• And more...

#Customize Translations

php artisan vendor:publish --tag="filament-module-manager-translations"

Edit files in lang/vendor/filament-module-manager/.

#🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

#Development Setup

# Clone repository
git clone https://github.com/AlizHarb/filament-module-manager.git

# Install dependencies
composer install

# Run tests
composer test

# Format code
composer format

#Testing

# Run all tests
composer test

# Run specific test
./vendor/bin/pest --filter=ModuleManagerTest

#💖 Sponsor This Project

If this package helps you, consider sponsoring its development:

Your support helps maintain and improve this package! 🙏

#🐛 Issues & Support

• 🐛 Bug Reports: Create an issue
• 💡 Feature Requests: Request a feature
• 💬 Discussions: Join the discussion

#📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

#🙏 Acknowledgments

• Filament PHP - Amazing admin panel framework
• Nwidart Laravel Modules - Solid module foundation
• Spatie - Excellent Laravel packages
• All contributors and supporters 🎉