Filament Modules v5.x

NOTE: This documentation is for version 5.x of the package, which supports Laravel 11+, Filament 4.x
and
nwidart/laravel-modules 11+. If you are using Filament 3.x, please refer
to 4.x documentation
or 3.x documentation if you are using Laravel 10.

This package brings the power of modules to Laravel Filament. It allows you to organize your filament code into fully
autonomous modules that can be easily shared and reused across multiple projects.
With this package, you can turn each of your modules into a fully functional Filament Plugin with its own resources,
pages, widgets, components and more. What's more, you don't even need to register each of these plugins in your main
Filament Panel. All you need to do is register the ModulesPlugin in your panel, and it will take care of the rest for
you.

This package is simple a wrapper of nwidart/laravel-modules package to make it work
with Laravel Filament.

Features

A command to prepare your module for Filament
A command to create a Filament Cluster in your module
A command to create additional Filament Plugins in your module
A command to create a new Filament resource in your module
A command to create a new Filament page in your module
A command to create a new Filament widget in your module
Organize your admin panel into Cluster, one for each supported module.

Requirements

The following is a table showing a matrix of supported filament and laravel versions for each version of this package:

Package Version	Laravel Version	Filament Version	nwidart/laravel-modules Version
5.x	11.x and 12.x	4.x	11.x or 12.x
4.x	11.x and 12.x	3.x	11.x or 12.x
3.x	10.x	3.x	11.x

v5.x of this package requires the following dependencies:

Laravel 11.x or 12.x
Filament 4.x or higher
PHP 8.2 or higher
nwidart/laravel-modules 11.x or 12.x

Installation

You can install the package via composer:

composer require coolsam/modules

This will automatically install nwidart/laravel-modules: ^11 (for Laravel 11) or nwidart/laravel-modules: ^12 (for
Laravel 12) as well. Make sure you go through
the documentation to understand how to use the package and to configure it
properly before proceeding.

Task: Configure your Laravel Modules first before continuing.

Autoloading modules

Don't forget to autoload modules by adding the merge-plugin to your composer.json according to the laravel modules documentation:

"extra": {
    "laravel": {
        "dont-discover": []
    },
    "merge-plugin": {
        "include": [
            "Modules/*/composer.json"
        ]
    }
},

Next, Run the installation command and follow the prompts to publish the config file and set up the package:

php artisan modules:install

Alternatively, you can just publish the config file with:

php artisan vendor:publish --tag="modules-config"

Configuration

After publishing the config file, you can configure the package to your liking. The configuration file is located
at config/filament-modules.php.

The following can be adjusted in the configuration file:

mode: The mode used by the package to discover and register resources from modules. This can be set to plugins,
panels or both (default). See the ConfigMode enum for details.
auto-register-plugins: If set to true, the package will automatically register all the plugins in your modules.
Otherwise, you will need to register each plugin manually in your Filament Panel.
clusters.enabled: If set to true, a cluster will be created in each module during the module:filament:install
command and all filament files for that module may reside inside that cluster. Otherwise, filament files will reside
in Filament/Resources, Filament/Pages, Filament/Widgets, etc.
clusters.use-top-navigation: If set to true, the top navigation will be used to navigate between clusters while
the actual links will be loaded as a side sub-navigation. In my opinion, this improves UX. Otherwise, the package will
honor the configuration that you have in your panel.
panels.group: The group under which the panels will be registered in the Main Panel's navigation. This is only
applicable if the mode is set to support panels. All links to the various module panels will be grouped under this
group in the main panel's navigation for ease of navigation.
panels.group-icon: The group icon used in the above navigation. This is only applicable if the mode is set to
support panels.
panels.open-in-new-tab: If set to true, the links to the module panels will open in a new tab. This is only
applicable if the mode is set to support panels.
panels.group-sort: The sort order applied on each navigation item in the modules panel group.

Usage

Register the plugin

The package comes with a ModulesPlugin that you can register in your Filament Panel. This plugin will automatically
load all the modules in your application and register them as Filament plugins if the mode supports plugins (either
PLUGINS or BOTH).
If the configuration mode supports panels, the module is also responsible for automatically creating navigation links
between the main panel and each of the module panels.
In order to achieve this, you need to register the ModulesPlugin in your panel of choice (e.g. Admin Panel) like so:

// e.g. in App\Providers\Filament\AdminPanelProvider.php
 
use Coolsam\Modules\ModulesPlugin;
public function panel(Panel $panel): Panel
{
    return $panel
        ...
        ->plugin(ModulesPlugin::make());
}

That's it! now you are ready to start creating some filament code in your module of choice!

Installing Filament in a module

If you don't have a module already, you can generate one using the module:make command like so:

php artisan module:make MyModule

Next, run the module:filament:install command to generate the necessary Filament files and directories in your module:

php artisan module:filament:install MyModule

This will guide you interactively on whether you want to organize your code in clusters, and whether you would like to
create a default cluster.
At the end of this installation, you will have the following structure in your module:

Modules
- MyModule
  - app
    - Filament
      - Clusters
        
        MyModule
        
        Pages
        
        Resources
        
        Widgets
        
        MyModule.php
      - Pages
      - Resources
      - Widgets
      - OneModulePanel
        
        Pages
        
        Resources
        
        Widgets
      - AnotherModulePanel
        
        Pages
        
        Resources
        
        Widgets
      - MyModulePlugin.php
    - Providers
      - Filament
        
        OneModulePanelServiceProvider.php
        
        AnotherModulePanelServiceProvider.php
      - MyModuleServiceProvider.php

As you can see, there are two main files generated: The plugin class and optionally the cluster class. After generation,
you are free to make any modifications to these classes as you may see fit. Optionally, Panels are also generated inside the module if supported.
All these can be generated individually later using their respective commands.

The plugin will be loaded automatically unless the configuration is set otherwise. As a result, it will also load
all its clusters automatically.

Panels will register their navigation links in the main panel's navigation if the configuration is set to support panels. In the individual panels, there will also
be a link to the main panel's navigation, allowing you to navigate back to the main panel.

Your module is now ready to be used in your Filament Panel. Use the following commands during development to generate
new resources, pages, widgets, plugins, panels and clusters in your module:

Creating a new resource

php artisan module:make:filament-resource
# Aliases
php artisan module:filament:resource
php artisan module:filament:make-resource

Follow the interactive prompts to create a new resource in your module.

Creating a new page

php artisan module:make:filament-page
# or
php artisan module:filament:page
php artisan module:filament:make-page

Follow the interactive prompts to create a new page in your module.

php artisan module:make:filament-widget
# or
php artisan module:filament:widget
php artisan module:filament:make-widget

Follow the interactive prompts to create a new widget in your module.

Creating a new cluster

php artisan module:make:filament-cluster
# or
php artisan module:filament:cluster
php artisan module:filament:make-cluster

Follow the interactive prompts to create a new cluster in your module.

Creating a new plugin

php artisan module:make:filament-plugin
# or
php artisan module:filament:plugin
php artisan module:filament:make-plugin

Follow the interactive prompts to create a new plugin in your module.

Create a new Filament Theme (WIP)

php artisan module:make:filament-theme
# or
php artisan module:filament:theme
php artisan module:filament:make-theme

Create a new Filament Panel (New!!)

php artisan module:make:filament-panel
# or
php artisan module:filament:panel
php artisan module:filament:make-panel

Follow the interactive prompts to create a new panel in your module.

Protecting your resources, pages and widgets (Access Control) - WIP

use Coolsam\Modules\Resource;

use the above resource class instead of use Filament/Resources/Resource; into your resource class file to protect your
resources.

use Coolsam\Modules\Page;

use the above page class instead of use Filament/Pages/Page; into your page class file to protect your pages.

use Coolsam\Modules\TableWidget;

use the above page class instead of use Filament/Pages/TableWidget; into your widget class file to protect your
TableWidget.

use Coolsam\Modules\ChartWidget;

use the above page class instead of use Filament/Pages/ChartWidget; into your widget class file to protect your
ChartWidget.

use Coolsam\Modules\StatsOverviewWidget;

use the above page class instead of use Filament/Pages/StatsOverviewWidget; into your widget class file to protect
your StatsOverviewWidget.

use CanAccessTrait;

use the above trait directly into your resource and page class file to protect your resources and pages.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

savannabits/filament-modules