README

Developer tooling for the Syriable Filament ecosystem. The package wires custom Artisan generators that scaffold translatable Filament resources and module plugins, a guard-aware Filament Shield role resource, and a panel plugin that bundles Syriable's translator, activity log, and Shield integrations.

Features

• syriable:make-resource — drop-in replacement for Filament's resource generator that extends TranslatableResource and translatable resource pages instead of Filament's base classes.
• Module-aware model discovery — interactive model selection searches Eloquent models under your modules/ directory.
• plugin:resource (CreatePluginCommand) — scaffolds a Filament panel plugin for an InterNACHI/modular module, auto-discovers its Filament components, and registers the plugin in the module service provider.
• Custom file generators — binds Syriable generators into Filament's make:filament-resource pipeline so generated code is translation-ready out of the box.
• UtilitiesPlugin — registers TranslatorPlugin, Activitylog, and FilamentShieldPlugin on a panel from a single entry point.
• Guard-aware RoleResource — extends Filament Shield's role resource with a live guard_name selector, per-guard permission matrices, and correct user counts across morph types.

Requirements

• PHP 8.4+
• Laravel 12 or 13
• Filament 5.5+
• bezhansalleh/filament-shield ^4.2
• syriable/filament-translator ^1.1
• syriable/filament-activitylog ^0.1

For plugin:resource, your application must use InterNACHI/modular with modules under the path configured in config/app-modules.php.

Installation

Install the package via Composer:

composer require syriable/filament-utilities

UtilitiesServiceProvider is auto-discovered. Register UtilitiesPlugin on every Filament panel that should use the bundled Syriable integrations:

use Filament\Panel;
use Syriable\Filament\Plugins\Utilities\UtilitiesPlugin;

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

UtilitiesPlugin registers the custom RoleResource, TranslatorPlugin, Activitylog, and FilamentShieldPlugin. You do not need to register those plugins separately when using UtilitiesPlugin.

Usage

Generate a translatable resource

Use syriable:make-resource (alias: syriable:resource) instead of make:filament-resource. It accepts the same options as Filament's command — panel selection, soft deletes, separate form/table schema classes, and so on.

php artisan syriable:make-resource Buyer --panel=dashboard

When no model argument is passed, the command interactively suggests Eloquent models discovered from classes loaded from your modules/ directory.

Generated classes extend Syriable's translatable bases:

Model namespaces are resolved relative to the selected resource namespace so module resources reference module models instead of App\Models.

After generation, add translation keys under lang/{locale}/ following the filament-translator convention. Enable createMissingTranslationKeys() during local development to scaffold missing keys automatically.

plugin:resource (CreatePluginCommand)

Scaffold a Filament panel plugin inside an InterNACHI/modular module:

php artisan plugin:resource users

The command reads config('app-modules.modules_directory') (default modules) and config('app-modules.modules_namespace') (default Modules) to resolve paths and namespaces.

What it generates

For php artisan plugin:resource users, the command creates:

modules/users/src/UsersPlugin.php

with namespace Modules\Users. The generated plugin class:

• implements Filament's Plugin contract,
• uses the module slug as its plugin ID (users),
• discovers resources, pages, and widgets under Filament/Resources, Filament/Pages, and Filament/Widgets relative to the plugin file.

Service provider registration

CreatePluginCommand also patches the module service provider at modules/{module}/src/Providers/{Module}ServiceProvider.php:

• adds the plugin use import when missing,
• appends $panel->plugin(UsersPlugin::make()) to an existing Panel::configureUsing() block, or
• creates a new Panel::configureUsing() block inside register() when none exists.

Re-running the command is safe — it skips registration when the plugin is already present.

Customize the generated plugin by publishing the stub before running the command (see Publish generator stubs).

Guard-aware role management

The package replaces Filament Shield's default RoleResource with a translatable variant that supports multiple authentication guards.

When creating or editing a role, the guard_name field is populated from config('auth.guards') and updates the permission matrix live. Changing the guard:

• swaps Filament Shield's resources.exclude and policies.methods config for guard-specific overrides from config/filament-utilities.php,
• flushes Shield's cached resource discovery so the permission checkboxes reflect the selected guard,
• prunes stale checkbox state so validation does not fail when switching between guards.

The roles table counts users via the model_has_roles pivot directly, so users_count is accurate when the same role is assigned to models on different guards (for example, Admin and Buyer).

Publish and customize the web-guard overrides:

php artisan vendor:publish --tag=filament-utilities-config

use Modules\Users\Filament\Resources\Admins\AdminResource;
use Syriable\Filament\Plugins\Utilities\Filament\Resources\Roles\RoleResource;

return [
    'shield' => [
        'resources' => [
            // Resources hidden from the permission matrix for the 'web' guard.
            'exclude' => [
                RoleResource::class,
                AdminResource::class,
            ],
        ],
        'policies' => [
            // Policy methods available in the permission matrix for the 'web' guard.
            'methods' => ['viewAny', 'view', 'create', 'update'],
        ],
    ],
    // ...
];

Non-web guards use your application's config/filament-shield.php values. Run php artisan shield:generate as usual to scaffold permissions and policies for application resources.

Publish generator stubs

Customize the plugin stub before running plugin:resource:

php artisan vendor:publish --tag=filament-utilities-stubs

Stubs are copied to stubs/filament-utilities/ in your application root.

Configuration

Publish the config file to customize translator path aliases, missing-key scaffolding, and Shield guard overrides:

php artisan vendor:publish --tag=filament-utilities-config

This copies config/filament-utilities.php to your application's config/ directory:

return [
    'shield' => [
        'resources' => [
            'exclude' => [
                // Resource classes omitted from the 'web' guard permission matrix.
            ],
        ],
        'policies' => [
            'methods' => ['viewAny', 'view', 'create', 'update'],
        ],
    ],
    'translator' => [
        // Scaffold missing translation keys while resolving labels.
        'create_missing_translation_keys' => true,

        // Map namespaces to translation path aliases.
        'path_aliases' => [
            'App\\Livewire' => 'livewire',
            'Modules\\Users\\Filament\\Resources' => 'modules/users',
        ],
    ],
];

UtilitiesPlugin reads these values when registering TranslatorPlugin, Activitylog, FilamentShieldPlugin, and the bundled RoleResource.

Opinionated Filament defaults and macros

The package ships several opt-in helpers. They are not applied automatically — call them from your own service provider's boot() method:

use Syriable\Filament\Plugins\Utilities\UtilitiesServiceProvider;

public function boot(): void
{
    UtilitiesServiceProvider::initializeFilamentComponents();
    UtilitiesServiceProvider::microFilamentComponents();
    UtilitiesServiceProvider::configureFactoryIcons();
    UtilitiesServiceProvider::configureActivitylogTimeline();
}

initializeFilamentComponents() applies global defaults via configureUsing():

• end-aligned form actions on pages,
• TextInput capped at 255 characters and trimmed,
• trimmed Textarea,
• consistent modal alignment/width for actions,
• a single-column responsive Schema default,
• when codewithdennis/filament-advanced-components is installed, AdvancedTextColumn values become clickable mailto: / tel: / https://wa.me/ links.

microFilamentComponents() registers convenience macros:

• ToggleButtons::fullWidth(),
• Section::prime() (a rounded, bordered container),
• Textarea::counter() — renders a live character counter using this package's filament-utilities::filament.components.textarea field wrapper.

configureFactoryIcons() registers your application's resources/svg/icons directory as a Blade Icons set (fluxwork, prefix flux).

configureActivitylogTimeline() applies compact defaults and a per-event icon map to syriable/filament-activitylog's ActivitylogTimeline component.

The AdvancedTextColumn integration requires the optional, paid codewithdennis/filament-advanced-components package. It is guarded by class_exists(), so the rest of the defaults work without it.

Testing

composer test

Other useful scripts:

composer analyse   # PHPStan (512M memory limit)
composer lint      # Laravel Pint

Run composer analyse instead of invoking PHPStan directly — the package analysis exceeds PHP's default 128M memory limit.

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

• Syriable

License

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