### Example: Interactive Install

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Interactive example of installing Filament support.

```bash
# Interactive
php artisan module:filament:install Users
```

--------------------------------

### Installation

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Install the coolsam/modules package and run the installation command.

```bash
composer require coolsam/modules
php artisan modules:install
```

--------------------------------

### Install Filament Support Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of installing Filament support for a new module.

```bash
# 1. Install Filament support
php artisan module:filament:install MyModule --cluster
```

--------------------------------

### Publishing Module as a Package - Installation

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Command for users to install a published module package.

```bash
composer require vendor/module-name
```

--------------------------------

### Example: Install with Cluster Option

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of installing Filament support with the cluster option pre-selected.

```bash
# With cluster option pre-selected
php artisan module:filament:install Users --cluster
```

--------------------------------

### Filament Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example configuration for filament-modules, showing mode, auto-registration, clusters, and panels settings.

```php
return [
    'mode' => 'both',              // 'plugins', 'panels', or 'both'
    'auto-register-plugins' => true,
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
    'panels' => [
        'group' => 'Modules',
        'group-sort' => 0,
        'open-in-new-tab' => false,
    ],
];
```

--------------------------------

### Create Panel and Add Resources Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of installing Filament, creating a panel, and then adding resources to that panel.

```bash
# 1. Install Filament support
php artisan module:filament:install Orders

# 2. Create a panel
php artisan module:filament:panel OrderDashboard Orders

# 3. Add resources to the panel
php artisan module:filament:resource OrderResource Orders --panel=orders-order-dashboard
```

--------------------------------

### File Structure

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example file structure after setting up a module with Filament support.

```text
Modules/MyModule/
├── app/
│   ├── Filament/
│   │   ├── Clusters/
│   │   │   ├── MyModule.php          # Cluster class
│   │   │   └── MyModule/
│   │   │       ├── Pages/            # Put pages here
│   │   │       ├── Resources/        # Put resources here
│   │   │       └── Widgets/          # Put widgets here
│   │   ├── Pages/                    # Standalone pages (optional)
│   │   ├── Resources/                # Standalone resources (optional)
│   │   └── Widgets/                  # Standalone widgets (optional)
│   ├── Models/
│   ├── Providers/
│   │   ├── MyModuleServiceProvider.php
│   │   └── Filament/
│   │       └── MyModulePlugin.php
│   └── ...
├── database/
│   └── migrations/
├── resources/
└── routes/

```

--------------------------------

### Manual Testing Workflow

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Step-by-step guide for manually testing a module.

```bash
# 1. Create module
php artisan module:make TestModule

# 2. Install Filament support
php artisan module:filament:install TestModule

# 3. Create test resource
php artisan module:filament:resource TestResource TestModule

# 4. View in browser
# Visit http://localhost:8000/admin (or your panel path)
# Should see TestModule cluster with TestResource

# 5. Disable module
php artisan module:disable TestModule

# 6. Visit admin again
# TestModule should disappear automatically
```

--------------------------------

### Resource Access Control Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example showing how module components automatically respect module state and user permissions.

```php
// In Modules/Users/Filament/Resources/UserResource.php
// If Users module disabled → resource hidden

// If module enabled but user has no permission → parent::canAccess() handles it
```

--------------------------------

### Configuration: Mixed Plugins and Panels

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Configuration example for 'both' mode with auto-registration enabled and clusters disabled.

```php
// config/filament-modules.php
return [
    'mode' => 'both',
    'auto-register-plugins' => true,
    'clusters' => [
        'enabled' => false,  // Simple navigation
    ],
];
```

--------------------------------

### Create Clusters

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of creating a cluster using Artisan and in code.

```bash
php artisan module:filament:cluster UserManagement Users
```

```php
namespace Modules\Users\Filament\Clusters;

use Filament\Clusters\Cluster;

class UserManagement extends Cluster
{
    protected static ?string $navigationIcon = 'heroicon-o-user-group';
}
```

```php
class UserResource extends Resource
{
    protected static ?string $cluster = UserManagement::class;
}
```

--------------------------------

### Extending Module Plugins

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of creating a custom module plugin and registering it.

```php
namespace Modules\Users\Filament;

use Coolsam\Modules\Concerns\ModuleFilamentPlugin;
use Filament\Contracts\Plugin;
use Filament\Navigation\NavigationGroup;
use Filament\Panel;

class UsersPlugin implements Plugin
{
    use ModuleFilamentPlugin;
    
    public function getId(): string
    {
        return 'users';
    }
    
    public function getModuleName(): string
    {
        return 'Users';
    }
    
    public function afterRegister(Panel $panel): void
    {
        // Custom setup after component discovery
        $panel->navigationGroups([
            NavigationGroup::make('User Management')
                ->icon('heroicon-o-user-group')
                ->collapsed(),
        ]);
    }
}
```

```php
// In panel provider
use Modules\Users\Filament\UsersPlugin;

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

--------------------------------

### Configuration: Separate Panels per Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Configuration example for 'panels' mode with auto-registration disabled.

```php
// config/filament-modules.php
return [
    'mode' => 'panels',
    'auto-register-plugins' => false,
    'panels' => [
        'group' => 'Module Dashboards',
        'open-in-new-tab' => true,
    ],
];
```

--------------------------------

### Module-Aware Resource Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of a Filament resource extending the module-aware base class `Coolsam\Modules\Resource`.

```php
namespace Modules\Users\Filament\Resources;

use Modules\Users\Models\User;
use Coolsam\Modules\Resource;  // <- Module-aware base class
use Filament\Forms;
use Filament\Tables;

class UserResource extends Resource
{
    protected static ?string $model = User::class;
    // ... configuration
}
```

--------------------------------

### Example: Create Module if it Doesn't Exist

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a module if it doesn't exist during Filament installation.

```bash
# Create module if it doesn't exist (interactive)
php artisan module:filament:install UnknownModule
# Prompts: "Module UnknownModule does not exist. Would you like to generate it?"
```

--------------------------------

### Programmatic Access to Module Information

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Examples of using the FilamentModules facade to get module information.

```php
use Coolsam\Modules\Facades\FilamentModules;

// Get a module
$module = FilamentModules::getModule('Users');

// Get all panels for a module
$panels = FilamentModules::getModulePanels('Users');

// Get all clusters for a module
$clusters = FilamentModules::getModuleClusters('Users');

// Check configuration mode
$mode = FilamentModules::getMode();
if ($mode?->shouldRegisterPlugins()) {
    // Plugins are enabled
}
```

--------------------------------

### Install Filament Support

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Command to install Filament support for a module, with prompts for cluster creation.

```bash
php artisan module:filament:install MyModule
# Choose: clusters (yes) → create default cluster (yes)
```

--------------------------------

### Module-Aware Page Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of a standalone page extending the module-aware base class `Coolsam\Modules\Page`.

```php
namespace Modules\Users\Filament\Pages;

use Coolsam\Modules\Page;  // <- Module-aware base class

class SettingsPage extends Page
{
    protected static ?string $navigationIcon = 'heroicon-o-cog-6-tooth';
    
    public function getTitle(): string
    {
        return 'Settings';
    }
}
```

--------------------------------

### Configuration: Single Admin Panel with Embedded Modules

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Configuration example for 'plugins' mode with auto-registration enabled.

```php
// config/filament-modules.php
return [
    'mode' => 'plugins',
    'auto-register-plugins' => true,
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
];
```

--------------------------------

### Associate Resource with Cluster

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of associating a resource with a cluster.

```php
class MyResourceResource extends Resource
{
    protected static ?string $cluster = MyModule::class;
}
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

A comprehensive example of the configuration file, demonstrating various settings.

```php
<?php

return [
    // Register plugins, panels, or both from modules
    'mode' => \Coolsam\Modules\Enums\ConfigMode::BOTH->value,
    
    // Auto-discover and register plugins
    'auto-register-plugins' => true,
    
    // Cluster configuration
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
    
    // Module panel navigation
    'panels' => [
        'group' => 'Panels',
        'group-icon' => \Filament\Support\Icons\Heroicon::OutlinedRectangleStack,
        'group-sort' => 0,
        'open-in-new-tab' => false,
    ],
];
```

--------------------------------

### Install Filament Support in Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Install Filament support for a specific module using the Artisan command.

```bash
php artisan module:filament:install Users
```

--------------------------------

### Accessing Module Data within Module Classes

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Examples of getting the current module name and module instance within module classes.

```php
// Get module name from class
$module = $this->getCurrentModuleName(); // Returns: 'mymodule'

// Get module instance
$module = Module::find('MyModule');
echo $module->getTitle(); // "MyModule"
```

--------------------------------

### Publishing Module as a Package - Composer Configuration

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example composer.json configuration for publishing a module as a package.

```json
{
  "name": "vendor/module-name",
  "type": "filament-module",
  "require": {
    "coolsam/modules": "^5.0"
  }
}
```

--------------------------------

### Create Panels

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of creating a separate panel for a module using Artisan and registering it.

```bash
php artisan module:filament:panel OrderDashboard Orders
```

```php
// In a service provider's boot method
\Filament\Facades\Filament::registerPanel(
    OrderDashboardPanel::make()
        ->id('order-dashboard')
        ->path('orders')
        ->login()
);
```

--------------------------------

### Automated Testing Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of an automated test for a resource using the TestsModules trait.

```php
use Coolsam\Modules\Testing\TestsModules;
use Livewire\Livewire;

class MyResourceTest extends TestCase
{
    use TestsModules;
    
    public function test_resource_renders()
    {
        $this->get('/admin/myresources')
            ->assertOk();
    }
}
```

--------------------------------

### get Registered Plugin Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example of using the static get() method to retrieve a registered plugin instance.

```php
$plugin = UsersPlugin::get();
```

--------------------------------

### Multi-Tenancy Pattern

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of implementing multi-tenancy by filtering Eloquent queries.

```php
class MyResource extends Resource
{
    public static function getEloquentQuery(): Builder
    {
        return parent::getEloquentQuery()
            ->where('tenant_id', auth()->user()->current_tenant_id);
    }
}
```

--------------------------------

### get Static Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/modules-plugin.md

Example of using the static get() method to retrieve the registered ModulesPlugin instance.

```php
use Coolsam\Modules\ModulesPlugin;

$plugin = ModulesPlugin::get();
```

--------------------------------

### Module-Aware Widget Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of a widget extending the module-aware base class `Coolsam\Modules\StatsOverviewWidget`.

```php
namespace Modules\Users\Filament\Widgets;

use Coolsam\Modules\StatsOverviewWidget;  // <- Module-aware base class
use Filament\Widgets\Stat;

class UserStatsWidget extends StatsOverviewWidget
{
    protected function getStats(): array
    {
        return [
            Stat::make('Total Users', User::count()),
            Stat::make('Active Users', User::where('active', true)->count()),
        ];
    }
}
```

--------------------------------

### Create Widget Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a widget for a module.

```bash
# 3. Create a widget
php artisan module:filament:widget ProductStatsWidget MyModule
```

--------------------------------

### Create Resource Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a resource for a module.

```bash
# 2. Create a resource
php artisan module:filament:resource ProductResource MyModule
```

--------------------------------

### boot Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/modules-plugin.md

Example of how to manually call the boot method of the ModulesPlugin.

```php
use Coolsam\Modules\ModulesPlugin;

$plugin = ModulesPlugin::make();
$plugin->boot($panel);
```

--------------------------------

### Mode Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of setting the 'mode' configuration option to 'both'.

```php
'mode' => 'both', // Register both plugins and panels
```

--------------------------------

### Create Page Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a custom page for a module.

```bash
# 4. Create a custom page
php artisan module:filament:page DashboardPage MyModule
```

--------------------------------

### Example: Interactive Plugin Creation

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Interactive example of creating a Filament plugin.

```bash
# Interactive
php artisan module:filament:plugin
```

--------------------------------

### Custom Cluster Navigation Pattern

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of defining custom navigation items for a cluster.

```php
class MyCluster extends Cluster
{
    public static function getNavigationItems(): array
    {
        return [
            NavigationItem::make('Cluster Item')
                ->icon('heroicon-o-heart')
                ->sort(1),
        ];
    }
}
```

--------------------------------

### Cluster Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Cluster class.

```php
namespace Modules\MyModule\Filament\Clusters;

use Filament\Clusters\Cluster;

class MyModule extends Cluster
{
    protected static ?string $navigationIcon = 'heroicon-o-squares-2x2';
}
```

--------------------------------

### Resource Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Resource class extended from Coolsam\Modules\Resource.

```php
namespace Modules\MyModule\Filament\Resources;

use Modules\MyModule\Models\MyModel;
use Coolsam\Modules\Resource;
use Filament\Forms;
use Filament\Tables;

class MyModelResource extends Resource
{
    protected static ?string $model = MyModel::class;
    protected static ?string $navigationIcon = 'heroicon-o-square-3-stack-3d';
    
    public static function form(Form $form): Form
    {
        return $form->schema([
            Forms\Components\TextInput::make('name')->required(),
        ]);
    }
    
    public static function table(Table $table): Table
    {
        return $table->columns([
            Tables\Columns\TextColumn::make('name'),
        ]);
    }
}
```

--------------------------------

### Example: Interactive Resource Creation

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Interactive example of creating a Filament resource.

```bash
# Interactive
php artisan module:filament:resource
```

--------------------------------

### Conditional Display Pattern

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of conditionally displaying a resource based on user role.

```php
class MyResource extends Resource
{
    public static function canAccess(): bool
    {
        // Hide unless user is admin
        if (!auth()->user()?->is_admin) {
            return false;
        }
        
        return parent::canAccess();
    }
}
```

--------------------------------

### Auto-Register Plugins Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of setting the 'auto-register-plugins' configuration option.

```php
'auto-register-plugins' => true,
```

--------------------------------

### Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example of setting the 'mode' in the filament-modules configuration file.

```php
// config/filament-modules.php
return [
    'mode' => ConfigMode::BOTH->value, // or: 'both'
];
```

--------------------------------

### Page Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Page class extended from Coolsam\Modules\Page.

```php
namespace Modules\MyModule\Filament\Pages;

use Coolsam\Modules\Page;

class SettingsPage extends Page
{
    protected static ?string $navigationIcon = 'heroicon-o-cog-6-tooth';
    
    public function getTitle(): string
    {
        return 'Settings';
    }
}
```

--------------------------------

### Example: Specify Plugin Name and Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a Filament plugin by specifying both the name and the module.

```bash
# Specify both name and module
php artisan module:filament:plugin UsersPlugin Users
```

--------------------------------

### Example: Specify Plugin Name, Prompt for Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a Filament plugin by specifying the name and being prompted for the module.

```bash
# Specify name, prompted for module
php artisan module:filament:plugin BlogPlugin
```

--------------------------------

### Clusters Use Top Navigation Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of enabling top navigation for clusters.

```php
'clusters' => [
    'use-top-navigation' => true,
],
```

--------------------------------

### Example Usage of Macros

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/service-provider.md

Demonstrates how to use registered module macros to get module information.

```php
use Nwidart\Modules\Facades\Module;

$module = Module::find('Users');
echo $module->getTitle(); // "Users"
echo $module->appNamespace('Models'); // "Modules\Users\Models"
```

--------------------------------

### Example: Specify Resource and Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a Filament resource by specifying the resource name and module.

```bash
# Specify resource and module
php artisan module:filament:resource UserResource Users
```

--------------------------------

### Accessing Module Data from Anywhere

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Examples of accessing module information (panels, clusters) from outside the module using the FilamentModules facade.

```php
use Coolsam\Modules\Facades\FilamentModules;

// Get module by name
$module = FilamentModules::getModule('MyModule');

// Get all panels in module
$panels = FilamentModules::getModulePanels('MyModule');

// Get all clusters in module
$clusters = FilamentModules::getModuleClusters('MyModule');
```

--------------------------------

### Example: Specify Resource with Specific Panel

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a Filament resource with a specified panel.

```bash
# With specific panel
php artisan module:filament:resource UserResource Users --panel=admin
```

--------------------------------

### Configuration File Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Example configuration for filament-modules.php.

```php
// config/filament-modules.php
return [
    'mode' => 'both',  // 'plugins' | 'panels' | 'both'
    'auto-register-plugins' => true,
    
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
    
    'panels' => [
        'group' => 'Modules',
        'group-icon' => Heroicon::OutlinedRectangleStack,
        'group-sort' => 0,
        'open-in-new-tab' => false,
    ],
];
```

--------------------------------

### Navigation Item Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example of creating navigation items using NavigationItem.

```php
NavigationItem::make($label)
    ->group($group)
    ->sort($groupSort)
    ->url($panel->getUrl())
    ->openUrlInNewTab($openInNewTab)
```

--------------------------------

### Override Module Access Control

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Example of overriding the default module-aware access control for a resource.

```php
class UserResource extends Resource
{
    public static function canAccess(): bool
    {
        // Custom logic
        if (auth()->user()?->role === 'superadmin') {
            return true;
        }
        
        // Fall back to module access control
        return parent::canAccess();
    }
}
```

--------------------------------

### Chart Widget Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Chart Widget class extended from Coolsam\Modules\ChartWidget.

```php
namespace Modules\MyModule\Filament\Widgets;

use Coolsam\Modules\ChartWidget;

class MyChartWidget extends ChartWidget
{
    protected static ?string $heading = 'Chart';
    
    protected function getType(): string
    {
        return 'line';
    }
    
    protected function getData(): array
    {
        return [
            'datasets' => [[
                'label' => 'Data',
                'data' => [10, 20, 30],
            ]],
            'labels' => ['Jan', 'Feb', 'Mar'],
        ];
    }
}
```

--------------------------------

### Panels Open in New Tab Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of configuring module panels to open in a new tab.

```php
'panels' => [
    'open-in-new-tab' => false,
],
```

--------------------------------

### Create a Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Use the Artisan command to create a new module.

```bash
php artisan module:make Users
```

--------------------------------

### Create Panel Command Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Examples of how to use the `module:filament:panel` command, both interactively and with specified arguments.

```bash
php artisan module:filament:panel

# Specify panel and module
php artisan module:filament:panel OrdersDashboard Orders
```

--------------------------------

### Stats Widget Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Stats Widget class extended from Coolsam\Modules\StatsOverviewWidget.

```php
namespace Modules\MyModule\Filament\Widgets;

use Coolsam\Modules\StatsOverviewWidget;
use Filament\Widgets\Stat;

class StatsWidget extends StatsOverviewWidget
{
    protected function getStats(): array
    {
        return [
            Stat::make('Total', Model::count()),
            Stat::make('Active', Model::where('active', true)->count()),
        ];
    }
}
```

--------------------------------

### Custom Access Override

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of overriding the canAccess method for custom access control in a resource.

```php
class AdminOnlyResource extends Resource
{
    public static function canAccess(): bool
    {
        // Must be admin AND module enabled
        if (!auth()->user()?->is_admin) {
            return false;
        }
        
        return parent::canAccess();
    }
}
```

--------------------------------

### Table Widget Base Class

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Example of a Filament Table Widget class extended from Coolsam\Modules\TableWidget.

```php
namespace Modules\MyModule\Filament\Widgets;

use Modules\MyModule\Models\MyModel;
use Coolsam\Modules\TableWidget;
use Filament\Tables;
use Filament\Tables\Table;

class MyModelsWidget extends TableWidget
{
    protected static ?int $sort = 2;
    
    public function table(Table $table): Table
    {
        return $table
            ->query(MyModel::query())
            ->columns([
                Tables\Columns\TextColumn::make('name'),
            ]);
    }
}
```

--------------------------------

### module:filament:page Example Usage

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Examples of how to use the module:filament:page command.

```bash
# Standalone page (interactive)
php artisan module:filament:page

# Specify page and module
php artisan module:filament:page SettingsPage Users

# Resource page
php artisan module:filament:page ListUsers Users --resource=UserResource
```

--------------------------------

### Run the installation command

Source: https://github.com/savannabits/filament-modules/blob/main/README.md

Run the installation command and follow the prompts to publish the config file and set up the package.

```bash
php artisan modules:install
```

--------------------------------

### shouldRegisterPlugins Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example usage of the shouldRegisterPlugins method.

```php
use Coolsam\Modules\Enums\ConfigMode;

$mode = ConfigMode::BOTH;
if ($mode->shouldRegisterPlugins()) {
    // Register plugins
}
```

--------------------------------

### File Structure Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

An example of the directory structure for Filament Modules.

```bash
output/
├── README.md                      # This file
├── integration-guide.md           # Setup and usage
├── configuration.md               # Configuration reference
├── types.md                       # Type definitions
│
└── api-reference/
    ├── modules.md                 # Modules class
    ├── modules-plugin.md          # ModulesPlugin class
    ├── service-provider.md        # ModulesServiceProvider
    ├── base-classes.md            # Resource, Page, Widgets
    ├── facade.md                  # FilamentModules facade
    ├── traits-and-concerns.md     # Traits and concerns
    └── commands.md                # Artisan commands
```

--------------------------------

### module:filament:widget Example Usage

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Examples of how to use the module:filament:widget command.

```bash
# Interactive (select module and widget type)
php artisan module:filament:widget

# Specify name and module
php artisan module:filament:widget StatsWidget Users
```

--------------------------------

### Example: Specify Resource with Model Namespace

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of creating a Filament resource with a specified model namespace.

```bash
# With model namespace
php artisan module:filament:resource UserResource Users --model=Modules\Users\Models\User
```

--------------------------------

### Panel not registering

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Troubleshooting steps for when a Filament panel is not registering correctly.

```php
// Check naming
Modules/MyModule/app/Providers/Filament/MyPanelProvider.php  // ✓ *PanelProvider pattern

// Check mode
config('filament-modules.mode')  // ✓ Should include 'panels'

// Check class path
Nwidart\Modules\Facades\Module::find('MyModule')
    ->getExtraPath('app/Providers/Filament/MyPanelProvider.php')  // ✓ File exists
```

--------------------------------

### Install Filament Support

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Installs Filament support in a module and creates the initial structure.

```bash
php artisan module:filament:install {module} [--cluster]
```

--------------------------------

### Install the package

Source: https://github.com/savannabits/filament-modules/blob/main/README.md

You can install the package via composer.

```bash
composer require coolsam/modules
```

--------------------------------

### Batch Create Resources Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of using the `module:filament:resource` command in a batch for multiple models.

```bash
# For each model
php artisan module:filament:resource UserResource Users --model=User
php artisan module:filament:resource ProductResource Inventory --model=Product
php artisan module:filament:resource OrderResource Orders --model=Order
```

--------------------------------

### Panels Group Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of setting the navigation group name for module panels.

```php
'panels' => [
    'group' => 'Modules',
],
```

--------------------------------

### Create Theme Command Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

The basic syntax for the `module:filament:theme` command.

```bash
php artisan module:filament:theme {name} {module?}
```

--------------------------------

### Usage Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/modules-plugin.md

This example shows how to register the ModulesPlugin within a Filament PanelProvider.

```php
use Coolsam\Modules\ModulesPlugin;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->login()
            ->plugin(ModulesPlugin::make())
            // ... other configuration
        ;
    }
}
```

--------------------------------

### Clusters Enabled Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of enabling support for organizing module Filament resources into clusters.

```php
'clusters' => [
    'enabled' => true,
],
```

--------------------------------

### Usage Example in Code

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example of using ConfigMode within application code to conditionally register components.

```php
use Coolsam\Modules\ModulesPlugin;
use Coolsam\Modules\Enums\ConfigMode;
use Filament\Panel;

class MyPlugin {
    public function register(Panel $panel): void
    {
        $mode = ConfigMode::tryFrom(config('filament-modules.mode'));
        
        if ($mode?->shouldRegisterPlugins()) {
            // Register module plugins
        }
        
        if ($mode?->shouldRegisterPanels()) {
            // Register module panels
        }
    }
}
```

--------------------------------

### make Factory Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example of using the static make() factory method to create a plugin instance.

```php
$plugin = UsersPlugin::make();
```

--------------------------------

### register Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/modules-plugin.md

Example of how to manually call the register method of the ModulesPlugin.

```php
use Coolsam\Modules\ModulesPlugin;
use Filament\Panel;

$plugin = ModulesPlugin::make();
$plugin->register($panel);
```

--------------------------------

### module:filament:cluster Example Usage

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Examples of how to use the module:filament:cluster command.

```bash
# Interactive
php artisan module:filament:cluster

# Specify cluster and module
php artisan module:filament:cluster UserManagement Users

# Specify panel
php artisan module:filament:cluster UserManagement Users --panel=admin
```

--------------------------------

### Accessing Current Mode

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Examples of how to access the current configuration mode.

```php
use Coolsam\Modules\Enums\ConfigMode;
use Coolsam\Modules\Facades\FilamentModules;

// From configuration
$mode = ConfigMode::tryFrom(config('filament-modules.mode'));

// From the Modules facade
$mode = FilamentModules::getMode();
```

--------------------------------

### Panels Group Sort Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of setting the sort order for the panels navigation group.

```php
'panels' => [
    'group-sort' => 0, // Appears first
],
```

--------------------------------

### UserStatsWidget Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/base-classes.md

Example of extending StatsOverviewWidget to display user-related statistics.

```php
use Coolsam\Modules\StatsOverviewWidget;
use Filament\Widgets\Stat;

class UserStatsWidget extends StatsOverviewWidget
{
    protected function getStats(): array
    {
        return [
            Stat::make('Total Users', User::count()),
            Stat::make('Active Users', User::where('active', true)->count()),
            Stat::make('New This Month', User::whereMonth('created_at', now()->month)->count()),
        ];
    }
}
```

--------------------------------

### In Code Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Example of creating a resource and accessing module information in code.

```php
use Coolsam\Modules\Facades\FilamentModules;
use Coolsam\Modules\Resource;

// Create a resource
class UserResource extends Resource
{
    protected static ?string $model = User::class;
    // ... Filament configuration
}

// Access module info
$mode = FilamentModules::getMode();
$panels = FilamentModules::getModulePanels('Users');
$clusters = FilamentModules::getModuleClusters('Users');
```

--------------------------------

### Panels Group Icon Configuration Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Example of setting the Filament icon for the panels navigation group.

```php
'panels' => [
    'group-icon' => \Filament\Support\Icons\Heroicon::OutlinedRectangleStack,
],
```

--------------------------------

### canAccess Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example showing how canAccess is used in a Resource class, relying on parent::canAccess() and module enabled state.

```php
use Coolsam\Modules\Resource;

class UserResource extends Resource
{
    public static function canAccess(): bool
    {
        return parent::canAccess(); // Returns true only if:
                                    // 1. Users module is enabled
                                    // 2. Filament's Resource::canAccess() returns true
    }
}
```

--------------------------------

### canAccess Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/base-classes.md

Example of manually checking access using the canAccess method.

```php
// Manually check access
if (UserResource::canAccess()) {
    echo 'Resource is accessible';
}
```

--------------------------------

### Modules Facade Access Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Example of accessing the `Modules` utility class via its facade.

```php
FilamentModules::getModule('Users')
```

--------------------------------

### make Factory Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/modules-plugin.md

Example of using the static make() factory method to create a new instance of ModulesPlugin.

```php
use Coolsam\Modules\ModulesPlugin;

$plugin = ModulesPlugin::make();
```

--------------------------------

### Access Control Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Example demonstrating how the `CanAccessTrait` automatically checks module enablement and parent access permissions.

```php
class UserResource extends Resource
{
    // Automatically checks:
    // 1. Is 'users' module enabled?
    // 2. Does parent::canAccess() return true?
}
```

--------------------------------

### Dependency Injection Usage Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

An example of using the Modules class via dependency injection.

```php
use Coolsam\Modules\Modules;

class MyService
{
    public function __construct(private Modules $modules)
    {
    }
    
    public function getModule(string $name)
    {
        return $this->modules->getModule($name);
    }
}
```

--------------------------------

### Access denied unexpectedly

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Debugging steps for unexpected access denial issues within a resource.

```php
// Check module state
Module::find('MyModule')->isEnabled()  // Check this

// Check parent access
parent::canAccess()  // If this returns false, resource hidden

// Override to debug
public static function canAccess(): bool {
    dd([
        'module_enabled' => Module::find(static::getCurrentModuleName())?->isEnabled(),
        'parent_access' => function_exists('canAccess') ? parent::canAccess() : true,
    ]);
}
```

--------------------------------

### Facade Methods

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Examples of using the FilamentModules facade.

```php
use Coolsam\Modules\Facades\FilamentModules;

// Get module
FilamentModules::getModule('Users');

// Get panels
FilamentModules::getModulePanels('Users');

// Get clusters
FilamentModules::getModuleClusters('Users');

// Get mode
FilamentModules::getMode();

// Convert path to namespace
FilamentModules::convertPathToNamespace($path);

// Get package path
FilamentModules::packagePath('stubs');
```

--------------------------------

### Get a Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

Example of retrieving a module by its name and accessing its properties.

```php
use Coolsam\Modules\Facades\FilamentModules;

$module = FilamentModules::getModule('Users');
echo $module->getStudlyName(); // 'Users'
```

--------------------------------

### Widget Generation

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/commands.md

Example of a generated Filament widget.

```php
// Modules/Users/app/Filament/Widgets/UserStatsWidget.php
namespace Modules\Users\Filament\Widgets;

use Coolsam\Modules\StatsOverviewWidget;
use Filament\Widgets\Stat;

class UserStatsWidget extends StatsOverviewWidget
{
    // ...
}
```

--------------------------------

### Create a Filament Resource in a Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

Create a Filament resource within a module, specifying the model.

```bash
php artisan module:filament:resource UserResource Users --model=User
```

--------------------------------

### Create Model (if needed)

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Command to create a model within a module, including migration.

```bash
php artisan make:model MyModel -m --path Modules/MyModule/app/Models
```

--------------------------------

### Get All Module Clusters

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

Example of retrieving all cluster classes for a given module.

```php
use Coolsam\Modules\Facades\FilamentModules;

$clusters = FilamentModules::getModuleClusters('Users');
foreach ($clusters as $clusterClass) {
    echo $clusterClass; // e.g., 'Modules\Users\Filament\Clusters\UserManagement'
}
```

--------------------------------

### Check Module Enabled State

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/integration-guide.md

A PHP snippet to verify if a specific module is enabled.

```php
Module::find('Users')->isEnabled()
```

--------------------------------

### Get All Module Panels

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

Example of fetching all panels associated with a specific module.

```php
use Coolsam\Modules\Facades\FilamentModules;

$panels = FilamentModules::getModulePanels('Users');
foreach ($panels as $panel) {
    echo $panel->getId(); // e.g., 'users-orders'
    echo $panel->getUrl();
}
```

--------------------------------

### Quick Creation Commands

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Available artisan commands for quick creation of Filament components within modules.

```bash
# Resource with all pages
php artisan module:filament:resource {Name} {Module}

# Standalone page
php artisan module:filament:page {Name} {Module}

# Widget (will ask type: Table/Chart/Stats)
php artisan module:filament:widget {Name} {Module}

# Cluster
php artisan module:filament:cluster {Name} {Module}

# Plugin
php artisan module:filament:plugin {Name} {Module}

```

--------------------------------

### Scenario 1: Single Admin Panel with All Modules as Plugins

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Configuration for loading all modules as plugins within the main admin panel.

```php
return [
    'mode' => 'plugins',
    'auto-register-plugins' => true,
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
    'panels' => [
        // Panel config is ignored in 'plugins' mode
    ],
];
```

--------------------------------

### Create a Panel

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Command to create a new Filament panel within a module.

```bash
php artisan module:filament:panel {Name} {Module}
```

--------------------------------

### Get Package Base Path

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

Examples of retrieving the base path of the package and a path to a specific file within the package.

```php
use Coolsam\Modules\Facades\FilamentModules;

$basePath = FilamentModules::packagePath();
// Returns: '/path/to/vendor/coolsam/modules'

$stubPath = FilamentModules::packagePath('stubs/resource.stub');
// Returns: '/path/to/vendor/coolsam/modules/stubs/resource.stub'
```

--------------------------------

### shouldRegisterPanels Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example usage of the shouldRegisterPanels method.

```php
use Coolsam\Modules\Enums\ConfigMode;

$mode = ConfigMode::BOTH;
if ($mode->shouldRegisterPanels()) {
    // Register panels
}
```

--------------------------------

### getCurrentModuleName Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example demonstrating how getCurrentModuleName extracts the module name.

```php
// Class: Modules\Users\Filament\Resources\UserResource
// Returns: 'users'
```

--------------------------------

### Location Array Type Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/types.md

Example of the location array structure.

```php
[
    'namespace' => 'Modules\Users\Filament\Pages',
    'path' => '/app/Modules/Users/resources/views/filament/pages',
    'viewNamespace' => 'users',
]
```

--------------------------------

### Debug Configuration

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Artisan tinker commands to check Filament Modules configuration settings.

```bash
php artisan tinker
> config('filament-modules.mode')
> config('filament-modules.auto-register-plugins')
> config('filament-modules.clusters.enabled')
```

--------------------------------

### getCurrentModuleName Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example demonstrating the usage of getCurrentModuleName in a Resource class.

```php
namespace Modules\Users\Filament\Resources;

class UserResource extends Resource
{
    // getCurrentModuleName() returns 'users'
}
```

--------------------------------

### getRelativeNamespace Method Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example implementation of the abstract getRelativeNamespace method in a subclass.

```php
protected function getRelativeNamespace(): string
{
    return 'Filament\\Resources';
}
```

--------------------------------

### getModuleName Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example implementation of the abstract getModuleName method for a module plugin.

```php
public function getModuleName(): string
{
    return 'Users';
}
```

--------------------------------

### Real-World Example: Module Plugin Discovery and Registration

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/facade.md

Demonstrates how to use the FilamentModules facade to discover and register plugins from enabled modules within a Filament panel.

```php
use Coolsam\Modules\Facades\FilamentModules;
use Filament\Panel;

class CustomModulePlugin
{
    public function register(Panel $panel): void
    {
        // Get configuration mode
        $mode = FilamentModules::getMode();
        if (!$mode?->shouldRegisterPlugins()) {
            return;
        }
        
        // Get all module names
        $modules = \Module::all();
        
        foreach ($modules as $module) {
            if (!$module->isEnabled()) {
                continue;
            }
            
            // Get clusters from this module
            $clusters = FilamentModules::getModuleClusters($module->getName());
            foreach ($clusters as $clusterClass) {
                // Register cluster...
            }
            
            // Get panels from this module
            $panels = FilamentModules::getModulePanels($module->getName());
            // Handle panels...
        }
    }
}
```

--------------------------------

### Create Resource

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Command to create a Filament resource for a model within a module.

```bash
php artisan module:filament:resource MyModelResource MyModule --model=MyModel
```

--------------------------------

### Separate Admin Panel Pattern

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Commands and code to create and register a separate admin panel within a module.

```bash
# Create panel in module
php artisan module:filament:panel Orders Orders

# Register panel in config or provider
\Filament\Facades\Filament::registerPanel(
    OrderPanel::make()
        ->id('orders')
        ->path('orders')
);

# Now accessible at /orders instead of /admin
```

--------------------------------

### Resource doesn't appear in panel

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/module-developer-quickstart.md

Troubleshooting steps for when a resource is not appearing in the Filament panel.

```php
// Check 1: Extend correct base class
use Coolsam\Modules\Resource;  // ✓ Correct

// Check 2: File location
Modules/MyModule/app/Filament/Resources/MyResource.php  // ✓ Correct

// Check 3: Module enabled
Module::find('MyModule')->isEnabled()  // ✓ Should be true

// Check 4: Plugin registered
->plugin(ModulesPlugin::make())  // ✓ In panel config
```

--------------------------------

### Scenario 2: Separate Panel per Module

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/configuration.md

Configuration for creating a separate panel for each module.

```php
return [
    'mode' => 'panels',
    'auto-register-plugins' => false,
    'clusters' => [
        'enabled' => true,
        'use-top-navigation' => true,
    ],
    'panels' => [
        'group' => 'Module Panels',
        'group-icon' => \Filament\Support\Icons\Heroicon::OutlinedRectangleStack,
        'group-sort' => 10,
        'open-in-new-tab' => true,
    ],
];
```

--------------------------------

### Basic Setup CLI Commands

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/README.md

Command-line interface commands for setting up Filament within a module.

```bash
# 1. Install Filament in a module
php artisan module:filament:install Users

# 2. Create a resource
php artisan module:filament:resource UserResource Users --model=User

# 3. Create a page
php artisan module:filament:page SettingsPage Users

# 4. Create a widget
php artisan module:filament:widget UserStatsWidget Users
```

--------------------------------

### getCurrentModuleName Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/base-classes.md

Example demonstrating how getCurrentModuleName extracts the module name.

```php
// For class: Modules\Users\Filament\Resources\UserResource
// Returns: 'users'
$moduleName = UserResource::getCurrentModuleName();
```

--------------------------------

### afterRegister Hook Example

Source: https://github.com/savannabits/filament-modules/blob/main/_autodocs/api-reference/traits-and-concerns.md

Example of overriding the afterRegister hook in a plugin to customize navigation groups.

```php
public function afterRegister(Panel $panel): void
{
    // Custom setup after component discovery
    $panel->navigationGroups([
        NavigationGroup::make('Users')
            ->icon('heroicon-o-user'),
    ]);
}
```