Filament Shield

https://github.com/bezhansalleh/filament-shield
Admin
Filament Shield is a package that provides easy and intuitive access management for Filament Panels,...
Tokens:111,895
Snippets:782
Trust Score:9.5
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### shield:setup usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

Example commands for running shield:setup with the --fresh flag and with tenant, force, and starred options.

```bash
php artisan shield:setup --fresh
php artisan shield:setup --tenant="App\Models\Team" --force --starred
```

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

### Clean slate setup

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Run this command to start fresh and follow the setup process from scratch.

```bash
php artisan shield:setup --fresh
```

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

### shield:install usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

Example invocations of the shield:install command: one without the --tenant flag and one with it to make the panel tenantable.

```bash
php artisan shield:install admin
php artisan shield:install admin --tenant
```

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

### shield:setup

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Sets up the Shield package, optionally refreshing the database, configuring tenancy, forcing the setup, or starring the repository.

```APIDOC
## [COMMAND] shield:setup

### Description
Sets up the Shield package, optionally refreshing the database, configuring tenancy, forcing the setup, or starring the repository.

### Usage
```bash
shield:setup [--fresh] [--tenant=] [--force] [--starred]
```

### Options
- `--fresh` - Refresh the database before setup.
- `--tenant=` - Specify the tenant model.
- `--force` - Force the operation without confirmation.
- `--starred` - Star the repository.
```

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

### Run Shield Setup Command

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Runs the interactive setup command for Filament Shield.

```bash
php artisan shield:setup
```

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

### Install Filament Shield via Composer

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Run this command to install the Filament Shield package.

```bash
composer require bezhansalleh/filament-shield
```

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

### shield:install

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Installs Shield for a given panel, optionally with tenancy support.

```APIDOC
## [COMMAND] shield:install

### Description
Installs Shield for a given panel, optionally with tenancy support.

### Usage
```bash
shield:install {panel} [--tenant]
```

### Arguments
- `panel` (string) - Required - The panel ID.

### Options
- `--tenant` - Enable tenancy support.
```

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

### FilamentShield Facade Method Calls

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example calls to the FilamentShield facade, showing methods for discovering resources, transforming resources, getting localized labels, and retrieving resource permissions. The facade forwards all public methods of the class statically.

```php
// examples
FilamentShield::discoverResources();                  // Collection
FilamentShield::transformResources();                 // ?array
FilamentShield::getLocalizedResourceLabel($resource); // string
FilamentShield::getResourcePermissions($key);         // ?array
FilamentShield::getAllResourcePermissionsWithLabels();// array
```

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

### createSuperAdminUsing usage example

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-super-admin-seeder-translation.md

Example of registering a closure to create a super admin user in a service provider's boot method.

```php
// in a service provider boot():
SuperAdminCommand::createSuperAdminUsing(fn () => User::create([
    'name' => 'Admin',
    'email' => 'admin@example.com',
    'password' => Hash::make('secret'),
]));
```

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

### shield:translation usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-super-admin-seeder-translation.md

Shows how to run the command with a locale, and with a panel and custom path.

```bash
php artisan shield:translation fr
php artisan shield:translation fr --panel=admin --path=lang/fr/custom.php
```

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

### Using getResources() to iterate resources

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example of iterating over the resources catalogue, accessing model, modelFqcn, and permissions.

```php
$resources = FilamentShield::getResources();
foreach ($resources as $fqcn => $resource) {
    // $resource['model'], $resource['modelFqcn'], $resource['permissions']['view']['key'] ...
}
```

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

### get() method implementation

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

Implementation of get() that returns the plugin instance from the Filament container. Throws if the plugin is not registered.

```php
/** @var static $plugin */
$plugin = filament(app(static::class)->getId());
```

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

### shield:setup command signature

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

The exact PHP property signature for the shield:setup command, defining options --fresh, --tenant, --force, and --starred.

```php
public $signature = 'shield:setup
    {--F|fresh : re-run the migrations}
    {--tenant= : Tenant model}
    {--force}
    {--starred : Skip the prompt to star the repo}
';
```

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

### HasWidgetShield usage example with getHeading()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/traits-entity-shield.md

Example widget using HasWidgetShield. Filament checks static::canView() before rendering the widget.

```php
class RevenueChart extends Widget
{
    use HasWidgetShield;

    protected function getHeading(): string
    {
        return 'Revenue';
    }
    // Filament checks static::canView() before rendering the widget
}
```

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

### Using getCustomPermissions() with localized labels

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example showing the output format when calling getCustomPermissions(true).

```php
FilamentShield::getCustomPermissions(true);
// ['View:SystemLog' => 'View System Log', ...]
```

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

### shield:install command signature

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

The exact signature of the shield:install command, defining the optional panel argument and the --tenant flag.

```php
protected $signature = 'shield:install {panel?} {--tenant}';
```

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

### get() method signature

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

Static method to retrieve the already-registered plugin instance for the current panel.

```php
public static function get(): static
```

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

### shield:seeder usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-super-admin-seeder-translation.md

Three example invocations of the shield:seeder command, showing force overwrite, direct permissions with users and generated passwords, and exporting all tenants/users with included passwords.

```bash
php artisan shield:seeder --force
```

```bash
php artisan shield:seeder --option=direct_permissions --with-users --generate-passwords=random --force
```

```bash
php artisan shield:seeder --all --include-passwords
```

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

### Custom Permission Key Builder Example

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example closure that returns the subject as-is for custom permissions, otherwise falls back to the default builder by returning null.

```php
FilamentShield::buildPermissionKeyUsing(
    function (string $entity, string $affix, string $subject, string $case, string $separator) {
        if ($entity === 'custom') {
            return $subject; // external permissions used as-is
        }
        return null; // default builder for everything else
    }
);
```

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

### get()

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

Returns the already-registered plugin instance for the current panel.

```APIDOC
## get()

### Description
Returns the already-registered plugin instance for the current panel. Throws whatever `Filament::getPanel()` throws when the plugin is not registered on the current panel.

### Method
`public static function get(): static`

### Returns
- **static** - The registered plugin instance.

### Example
```php
$plugin = FilamentShieldPlugin::get();
```
```

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

### defaultPermissionKeyBuilder usage example

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example call to defaultPermissionKeyBuilder with 'viewAny', ':', 'Post', and 'pascal', producing 'ViewAny:Post'.

```php
FilamentShield::defaultPermissionKeyBuilder('viewAny', ':', 'Post', 'pascal'); // "ViewAny:Post"
```

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

### CanBeCentralApp: usage examples

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

Shows how to enable central app mode with a default true condition or with a closure that reads from config.

```php
FilamentShieldPlugin::make()->centralApp();            // default true
FilamentShieldPlugin::make()->centralApp(fn (): bool => config('app.central', false));
```

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

### CanCustomizeColumns: usage example

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

Shows how to chain setter methods to customize the layout of permission tabs.

```php
FilamentShieldPlugin::make()
    ->gridColumns(['default' => 1, 'sm' => 2, 'lg' => 3])
    ->sectionColumnSpan(1)
    ->checkboxListColumns(['default' => 1, 'sm' => 2, 'lg' => 4])
    ->resourceCheckboxListColumns(['default' => 1, 'sm' => 2]);
```

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

### Customize permission key generation in boot()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Use FilamentShield::buildPermissionKeyUsing() in the boot method to customize how permission keys are generated. The example handles Resource, Page, and Widget entities, and notes that if configurePermissionIdentifierUsing() was used previously, the logic needs adjustment.

```php
//...
public function boot(): void
{
    FilamentShield::buildPermissionKeyUsing(
            function (string $entity, string $affix, string $subject, string $case, string $separator) {
                return match(true) {
                    # if `configurePermissionIdentifierUsing()` was used previously, then this needs to be adjusted accordingly
                    is_subclass_of($entity, Resource::class) => Str::of($affix)
                        ->snake()
                        ->append('_')
                        ->append(
                            Str::of($entity)
                                ->afterLast('\\')
                                ->beforeLast('Resource')
                                ->replace('\\', '')
                                ->snake()
                                ->replace('_', '::')
                        )
                        ->toString(),
                    is_subclass_of($entity, Page::class) => Str::of('page_')
                        ->append(class_basename($entity))
                        ->toString(),
                    is_subclass_of($entity, Widget::class) => Str::of('widget_')
                        ->append(class_basename($entity))
                        ->toString()
                    };
            });
}
```

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

### FilamentShieldPlugin::make()

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

Creates a new instance of the FilamentShieldPlugin. The example shows chaining various customization methods.

```APIDOC
## FilamentShieldPlugin::make()

### Description
Creates a new instance of the FilamentShieldPlugin. The example shows chaining various customization methods.

### Method
`make()`

### Parameters
None.

### Return Value
- **FilamentShieldPlugin** - A new plugin instance.

### Example
```php
FilamentShieldPlugin::make()
    ->navigationLabel('Roles')
    ->navigationIcon('heroicon-o-shield-check')
    ->navigationGroup('Access Control')
    ->globallySearchable(true)
    ->parentResource(SomeParentResource::class);
```
```

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

### shield:super-admin command usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-super-admin-seeder-translation.md

Bash commands to run the shield:super-admin command with various options.

```bash
php artisan shield:super-admin
php artisan shield:super-admin --user=1 --panel=admin
php artisan shield:super-admin --tenant=42 --panel=admin
```

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

### Using ShieldConfig via Utils::getConfig()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-shield-config.md

Example of accessing nested configuration values through the ShieldConfig bag. Shows how associative arrays become nested ShieldConfig instances and list arrays remain plain arrays.

```php
use BezhanSalleh\FilamentShield\Support\Utils;

$config = Utils::getConfig();

$config->permissions->separator;               // ':'  (nested ShieldConfig)
$config->permissions->case;                    // 'pascal'
$config->super_admin->name;                    // 'super_admin'
$config->resources->exclude;                   // [] (list kept as array)
$config->tenant_model;                         // null
$config->custom_permissions;                   // [] (empty array)
```

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

### Enforce Policies with Closure Condition

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Example that enforces policies only for the admin panel, skipping the Post model.

```php
FilamentShield::enforcePolicies(
    fn (): bool => Filament::getCurrentPanel()?->getId() === 'admin',
    except: [Post::class],
);
```

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

### Stringer usage example: append and delete line

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/stringer.md

Shows how to use Stringer to edit a config file: append a tenant_model line and then delete it. Uses the fluent API and saves the changes.

```php
use BezhanSalleh\FilamentShield\Stringer;

Stringer::for(config_path('filament-shield.php'))
    ->append('tenant_model', "'tenant_model' => '" . Team::class . "',")
    ->deleteLine('tenant_model')
    ->save();
```

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

### Generate policies with shield:generate

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-generate.md

Example commands for generating policies using the shield:generate artisan command. The first generates policies for all resources in the admin panel. The second generates policies for specific resources with the policies option. The third excludes resources and ignores existing policies. The fourth generates policies with relationships.

```bash
php artisan shield:generate --all --panel=admin
```

```bash
php artisan shield:generate --resource=PostResource,CommentResource --option=policies --panel=admin
```

```bash
php artisan shield:generate --resource=CommentResource --exclude --ignore-existing-policies
```

```bash
php artisan shield:generate --panel=admin --relationships
```

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

### Set Auth Provider Model in Config

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Example config snippet showing where to set the auth_provider_model to your User model.

```php
// config/filament-shield.php
return [
    // ...
    'auth_provider_model' => 'App\\Models\\User',
    // ...
];
```

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

### Configure resources permissions in Filament Shield

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Example configuration for the 'resources' array in Filament Shield's config file. Set 'subject' to 'class' or 'model' (default 'model'). Use 'manage' to define resource-specific policy methods, which are generated in addition to global methods when 'policies.merge' is true. Use 'exclude' to skip permission generation for specific resources.

```php
'resources' => [
    'subject' => 'model',
    'manage' => [
        \BezhanSalleh\FilamentShield\Resources\Roles\RoleResource::class => [
            'viewAny',
            'view',
            'create',
            'update',
            'delete',
        ],
    ],
    'exclude' => [
        //
    ],
],
```

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

### HasSimpleResourcePermissionView: usage example

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

Enables the simple resource permission view, rendering the Resources tab as a flat checkbox list.

```php
FilamentShieldPlugin::make()->simpleResourcePermissionView();
```

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

### Register FilamentShieldPlugin on a panel

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

Shows how to register the plugin on a Filament panel using the centralApp() method. This is the typical setup for enabling the plugin.

```php
use BezhanSalleh\FilamentShield\FilamentShieldPlugin;

$panel->plugins([
    FilamentShieldPlugin::make()
        ->centralApp(),
]);
```

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

### shield:publish command usage examples

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

Shows three invocations of the shield:publish Artisan command. The first publishes to the admin panel. The second adds the --cluster and --force flags to publish within a cluster and overwrite existing files. The third uses --nested to nest the resource inside OrderResource.

```bash
php artisan shield:publish --panel=admin
php artisan shield:publish --panel=admin --cluster=Settings --force
php artisan shield:publish --panel=admin --nested=OrderResource
```

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

### Adding SyncShieldTenant to panel tenantMiddleware

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/middleware.md

Shows how to manually add the SyncShieldTenant middleware to a tenanted panel's tenantMiddleware stack with isPersistent set to true. This is typically done automatically by shield:install --tenant.

```php
// app/Providers/Filament/AdminPanelProvider.php
$panel->tenantMiddleware([
    \BezhanSalleh\FilamentShield\Middleware\SyncShieldTenant::class,
], isPersistent: true);
```

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

### Customize FilamentShieldPlugin with Essentials traits

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

Example usage of the inherited methods to set navigation label, icon, group, enable global search, and set a parent resource. Requires the external package bezhansalleh/filament-plugin-essentials.

```php
FilamentShieldPlugin::make()
    ->navigationLabel('Roles')
    ->navigationIcon('heroicon-o-shield-check')
    ->navigationGroup('Access Control')
    ->globallySearchable(true)
    ->parentResource(SomeParentResource::class);
```

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

### GET /{panel-path}/{resource-slug}/

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/endpoints.md

Lists all roles in a table view with a toolbar action to create a new role. This endpoint is handled by the ListRoles page.

```APIDOC
## GET /{panel-path}/{resource-slug}/

### Description
Lists all roles in a table view with a toolbar action to create a new role. This endpoint is handled by the ListRoles page.

### Method
GET

### Endpoint
`/{panel-path}/{resource-slug}/`

### Parameters
#### Path Parameters
- **panel-path** (string) - Required - The panel path from the panel provider (e.g., `/admin`).
- **resource-slug** (string) - Required - The resource slug from `filament-shield.shield_resource.slug` (default `'shield/roles'`).

### Response
#### Success Response (200)
- **name** (string) - The role name, headline-formatted and searchable.
- **guard_name** (string) - The guard name, displayed as a warning badge.
- **team.name** (string) - The team name, displayed as a badge (default `'Global'`, central-app only).
- **permissions_count** (integer) - The count of permissions, displayed as a badge.
- **updated_at** (datetime) - The last update timestamp.

#### Response Example
Full HTML page rendered by Filament.
```

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

### toLocalizationKey(string $key): string

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Converts a permission key to a translation key by replacing the configured separator with underscores, applying snake_case, and collapsing double underscores. For example, 'ViewAny:Post' becomes 'view_any_post'.

```APIDOC
## toLocalizationKey(string $key): string

### Description
Converts a permission key to a translation key: replaces the configured `permissions.separator` with `_`, applies `snake()`, and collapses double underscores. E.g. `ViewAny:Post` → `view_any_post`.

### Method
Static method

### Signature
`public static function toLocalizationKey(string $key): string`

### Parameters
- **$key** (string) - Required - The permission key to convert.

### Return Value
- **string** - The converted translation key.

### Example
```php
Utils::toLocalizationKey('ViewAny:Post'); // returns 'view_any_post'
```
```

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

### boot(Panel $panel)

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

Empty boot method, does nothing.

```APIDOC
## boot(Panel $panel)

### Description
Empty body, does nothing.

### Method
`public function boot(Panel $panel): void`

### Parameters
- **$panel** (Panel) - Required - The Filament panel instance.

### Returns
- **void**

### Example
```php
$plugin->boot($panel);
```
```

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

### boot() method signature

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

Empty boot method, no actions performed.

```php
public function boot(Panel $panel): void
```

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

### Runtime override of Filament Shield config with config()->set()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/configuration.md

Shows how to set 'filament-shield.permissions.separator' and 'filament-shield.permissions.case' at runtime. Because ShieldConfig::init() re-reads config() on every call, these changes are honored immediately. The example then reads the separator value via Utils::getConfig()->permissions->separator, which returns '::'.

```php
config()->set('filament-shield.permissions.separator', '::');
config()->set('filament-shield.permissions.case', 'snake');

Utils::getConfig()->permissions->separator; // '::'
```

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

### Get permission catalogue for current panel

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Sets the current panel to 'admin' and calls FilamentShield::getEntitiesPermissions() to retrieve a flat array of permission keys. The method is resolved for the current panel; in artisan commands, jobs, or tests, set the panel first. Results are memoized for the request lifetime.

```php
use BezhanSalleh\FilamentShield\Facades\FilamentShield;
use Filament\Facades\Filament;

Filament::setCurrentPanel('admin');

FilamentShield::getEntitiesPermissions();
// ['ViewAny:User', 'View:User', 'Create:User', ..., 'View:Settings', 'View:IncomeWidget', 'Impersonate:User']
```

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

### Prohibit destructive commands with FilamentShield::prohibitDestructiveCommands

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/commands-setup-install-publish.md

Use this snippet in a service provider's boot() method to prohibit destructive commands (generate, install, publish, seeder, setup, super-admin) when the application is in production. Note that shield:translation is not prohibited.

```php
use BezhanSalleh\FilamentShield\Facades\FilamentShield;

// in a service provider boot():
FilamentShield::prohibitDestructiveCommands($this->app->isProduction());
```

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

### Import FilamentShield Facade and Class

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Shows how to import the FilamentShield facade and the core class for direct resolution via the container binding 'filament-shield'.

```php
use BezhanSalleh\FilamentShield\Facades\FilamentShield;
// or
use BezhanSalleh\FilamentShield\FilamentShield; // direct resolution: app('filament-shield')
```

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

### Using FilamentShield Facade Methods

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

Shows how to call facade methods like getResources() and prohibitDestructiveCommands() after importing the facade.

```php
use FilamentShield;

FilamentShield::getResources();
FilamentShield::prohibitDestructiveCommands(app()->isProduction());
```

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

### CanLocalizePermissionLabels: usage example

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

Enables localization of permission labels, which is the default behavior.

```php
FilamentShieldPlugin::make()->localizePermissionLabels();
```

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

### Publish new config and resource

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Run these artisan commands to publish the new configuration file and the RoleResource. The second command can be ignored if the resource was not previously published.

```bash
php artisan vendor:publish --tag="filament-shield-config"
php artisan shield:publish --panel=admin # you can ignore this if you didn't published the resource previously
```

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

### make()

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

Resolves a new instance of the plugin from the container.

```APIDOC
## make()

### Description
Resolves a new instance of the plugin from the container.

### Method
`public static function make(): static`

### Returns
- **static** - A new plugin instance.

### Example
```php
$plugin = FilamentShieldPlugin::make();
```
```

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

### make() method signature

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

Static factory method that resolves a new instance from the container.

```php
public static function make(): static
```

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

### GET /{panel-path}/{resource-slug}/{record}

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/endpoints.md

Displays the details of a specific role. This endpoint is handled by the ViewRole page.

```APIDOC
## GET /{panel-path}/{resource-slug}/{record}

### Description
Displays the details of a specific role. This endpoint is handled by the ViewRole page.

### Method
GET

### Endpoint
`/{panel-path}/{resource-slug}/{record}`

### Parameters
#### Path Parameters
- **panel-path** (string) - Required - The panel path from the panel provider (e.g., `/admin`).
- **resource-slug** (string) - Required - The resource slug from `filament-shield.shield_resource.slug` (default `'shield/roles'`).
- **record** (string) - Required - The role record identifier.

### Response
#### Success Response (200)
Full HTML page rendered by Filament.
```

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

### getResources(): ?array

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Returns a catalogue of resources keyed by resource FQCN, including model and permission information.

```APIDOC
## getResources(): ?array

### Description
Returns a catalogue of resources keyed by resource FQCN, including model and permission information.

### Method
GET (PHP method)

### Endpoint
FilamentShield::getResources()

### Parameters
None

### Request Example
```php
$resources = FilamentShield::getResources();
```

### Response
#### Success Response
- **array<string, array{resourceFqcn: string, model: string, modelFqcn: string, permissions: array<string, array{key: string, label: string}>}>** - Catalogue keyed by resource FQCN.

#### Response Example
```php
foreach ($resources as $fqcn => $resource) {
    // $resource['model'], $resource['modelFqcn'], $resource['permissions']['view']['key'] ...
}
```
```

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

### prependBeforeLast(string $needle, string $replacement): static

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/stringer.md

Inserts replacement at the start of the line containing the last occurrence of the needle.

```APIDOC
## prependBeforeLast(string $needle, string $replacement): static

### Description
Finds the **last** occurrence of `$needle` and inserts the replacement at the start of that line, preserving the original line indentation. Used by relationship generation to inject methods before the final `}` of a model class.

### Method
prependBeforeLast

### Parameters
- **needle** (string) - Required - text locating the target line
- **replacement** (string) - Required - content to insert

### Return
static
```

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

### Synchronize permissions with seeder using getEntitiesPermissions

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Iterates over the permission catalogue and uses Spatie\Permission\Models\Permission::firstOrCreate() to ensure each permission exists with the 'web' guard. This method only reads and never creates permission rows, so this seeder is a typical use case for deploy-time synchronization.

```php
use BezhanSalleh\FilamentShield\Facades\FilamentShield;
use Spatie\Permission\Models\Permission;

foreach (FilamentShield::getEntitiesPermissions() as $key) {
    Permission::firstOrCreate(['name' => $key, 'guard_name' => 'web']);
}
```

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

### Using getEntitiesPermissions() to create permissions

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Sets the current panel to 'admin' and iterates over the returned permission keys to create each permission with the 'web' guard. Requires Filament::setCurrentPanel() outside panel requests.

```php
Filament::setCurrentPanel('admin');
foreach (FilamentShield::getEntitiesPermissions() as $key) {
    Permission::firstOrCreate(['name' => $key, 'guard_name' => 'web']);
}
```

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

### Idempotent mutation with when() and contains()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/stringer.md

Example from CanMakePanelTenantable::activateTenancy() showing the package's pattern: guard mutations with contains() and call save() inside ->when(condition, callback).

```php
$stringer->when(
    value: (! $stringer->contains($shieldMiddleware) && $stringer->contains($tenantMiddlewareMarker)),
    callback: fn (Stringer $stringer): bool => $stringer
        ->indent(4)
        ->append('->tenantMiddleware([', $shieldMiddleware)
        ->save()
);
```

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

### Generate policies for all resources

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Run this command to ensure all policies are up to date with the latest version of Shield when you haven't customized your policies.

```bash
php artisan shield:generate --all --option=policies
```

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

### Enforce Widget Permissions with HasWidgetShield

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Example of a Filament widget class using the HasWidgetShield trait to automatically hide rendering and restrict access if the user lacks permission.

```php
<?php

namespace App\Filament\Widgets;

use ...;
use BezhanSalleh\FilamentShield\Traits\HasWidgetShield;

class IncomeWidget extends LineChartWidget
{
    use HasWidgetShield;
    ...
}
```

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

### FilamentShield::discoverResources()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Discovers all resources based on configuration. Returns a Collection of resources.

```APIDOC
## FilamentShield::discoverResources()

### Description
Discovers all resources based on the `discovery.discover_all_resources` config. When enabled, collects resources across all panels; otherwise, from the current panel only.

### Method
Facade method (static)

### Endpoint
FilamentShield::discoverResources()

### Parameters
None

### Return Value
- **Collection** - A collection of discovered resources.

### Example
```php
$resources = FilamentShield::discoverResources();
```
```

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

### Enforce Page Permissions with HasPageShield

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Example of a Filament page class using the HasPageShield trait to automatically hide navigation and restrict access if the user lacks permission.

```php
<?php

namespace App\Filament\Pages;

use ...;
use BezhanSalleh\FilamentShield\Traits\HasPageShield;

class MyPage extends Page
{
    use HasPageShield;
    ...
}
```

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

### Generated Shield Permission Labels Translation File

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Example of the generated translation file at lang/en/shield-permissions.php. It contains keys for resource affixes, pages, widgets, and custom permissions, all in snake_case.

```php
<?php

/**
 * Shield Permission Labels
 *
 * Translate the values below to localize permission labels in your application.
 */

return [
    // Resource affixes
    'create' => 'Create',
    'delete' => 'Delete',
    'delete_any' => 'Delete Any',
    'force_delete' => 'Force Delete',
    'force_delete_any' => 'Force Delete Any',
    'replicate' => 'Replicate',
    'reorder' => 'Reorder',
    'restore' => 'Restore',
    'restore_any' => 'Restore Any',
    'update' => 'Update',
    'view' => 'View',
    'view_any' => 'View Any',

    // Pages (permission key in snake_case)
    'view_dashboard' => 'Dashboard',

    // Widgets (permission key in snake_case)
    'view_stats_overview' => 'Stats Overview',

    // Custom permissions
    'approve_posts' => 'Approve Posts',
];
```

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

### Seeder Command Options Recap

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Recap of options for the shield:seeder command. Use --generate to generate the seeder file, --option to choose the seeder type, --with-users to export users based on roles/permissions, --all to export all tenants/users, --include-passwords to include existing hashed passwords, --generate-passwords to generate passwords (random, prompt, or custom value), and --force to overwrite the existing seeder file.

```bash
--generate    Generate seeder file
--option=permissions_via_roles|direct_permissions   Choose seeder type
--with-users    Export users based on their roles/permissions
--all   Export all tenants/users regardless of role assignments
--include-passwords Include existing hashed passwords from database
--generate-passwords=   Generate passwords (random, prompt, or custom value)
--force   Overwrite existing seeder file
```

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

### ShieldConfig init method

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-shield-config.md

Static method that creates a new ShieldConfig instance from the 'filament-shield' config. Not memoized, so it re-reads config on every call.

```php
public static function init(): self
```

```php
return static::$instance = new self(config('filament-shield'));
```

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

### Generate policies for specific resources

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Run this command to generate policies for specific resources. Use this when your policies are customized to avoid unwanted side effects, then manually review and adjust the customized policies.

```bash
php artisan shield:generate --resource=FooResource,BarResource --option=policies
```

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

### CanBeCentralApp::centralApp(bool | Closure $condition = true): static

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

Sets whether the panel is a central app in a multi-tenancy setup. When enabled, the RoleResource form/table shows the team field. The condition can be a boolean or a closure that is evaluated.

```APIDOC
## CanBeCentralApp::centralApp(bool | Closure $condition = true): static

### Description
Sets whether the panel is a central app in a multi-tenancy setup. When enabled, the RoleResource form/table shows the team field. The condition can be a boolean or a closure that is evaluated.

### Method
centralApp

### Signature
public function centralApp(bool | Closure $condition = true): static

### Parameters
- **$condition** (bool | Closure) - Optional - Default: true. If a closure is provided, it is evaluated using `EvaluatesClosures::evaluate()`.

### Return Value
static - Returns the plugin instance for chaining.

### Example
```php
FilamentShieldPlugin::make()->centralApp(); // default true
FilamentShieldPlugin::make()->centralApp(fn (): bool => config('app.central', false));
```
```

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

### Generation entry points

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Methods for generating permissions for resources, pages/widgets, and extra permissions. All driven by FilamentShield facade getters.

```php
public static function generateForResource(string $resourceKey): void       // :279 — creates all permissions for a resource FQCN, then gives them to the super admin
public static function generateForPageOrWidget(string $name): void          // :288 — createPermission + giveSuperAdminPermission
public static function generateForExtraPermissions(): void                  // :293 — creates all custom-permission keys, then gives them to super admin
```

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

### Customize policy discovery with Gate::guessPolicyNamesUsing

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Teach Laravel's policy discovery your convention using Gate::guessPolicyNamesUsing(). Adapt the callback to your configured namespace if you use a custom policies.path, since discovery does not look inside custom paths automatically.

```php
use Illuminate\Support\Facades\Gate;

Gate::guessPolicyNamesUsing(function (string $modelClass) {
    return str_replace('Models', 'Policies', $modelClass) . 'Policy';
});
```

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

### Preserve previous permission pattern

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Add this code to your AppServiceProvider's boot() method to preserve the previous versions (3.x|4.x-Beta*) permission pattern.

```php
use BezhanSalleh\FilamentShield\Facades\FilamentShield;
use Filament\Pages\BasePage as Page;
use Filament\Resources\Resource;
use Filament\Widgets\Widget;
use Illuminate\Support\Str;
```

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

### getWidgets(): ?array

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Returns a catalogue of widgets keyed by widget FQCN, including associated permissions.

```APIDOC
## getWidgets(): ?array

### Description
Returns a catalogue of widgets keyed by widget FQCN, including associated permissions.

### Method
GET (PHP method)

### Endpoint
FilamentShield::getWidgets()

### Parameters
None

### Request Example
```php
$widgets = FilamentShield::getWidgets();
```

### Response
#### Success Response
- **array<string, array{widgetFqcn: string, permissions: array<string, string>}>** - Catalogue keyed by widget FQCN.

#### Response Example
```php
// Example structure
[
    'App\Filament\Widgets\StatsOverview' => [
        'widgetFqcn' => 'App\Filament\Widgets\StatsOverview',
        'permissions' => [
            'view' => 'view_stats_overview',
        ],
    ],
]
```
```

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

### SyncShieldTenant handle method with docblock

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/middleware.md

The full handle method with its docblock, showing the parameter types and return type. This is the method that synchronizes the team context.

```php
/**
 * Handle an incoming request.
 *
 * @param  Closure(Request):Response  $next
 */
public function handle(Request $request, Closure $next): Response
```

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

### configurePackage method declaration

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

Declares the configurePackage method that configures the package with name, config file, translations, and commands.

```php
/** {@inheritDoc} */
public function configurePackage(Package $package): void
```

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

### getWidgets() method signature

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Returns the widget catalogue keyed by widget FQCN.

```php
public function getWidgets(): ?array
```

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

### Enable simple resource permission view with FilamentShieldPlugin

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Use this method to make the resource tab have a simple view like the other tabs.

```php
FilamentShieldPlugin::make()
    ->simpleResourcePermissionView()
```

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

### Run Filament Shield Tests

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Execute the test suite for the Filament Shield package using Composer.

```bash
composer test
```

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

### getResources() method signature

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/filament-shield.md

Returns the resource catalogue keyed by resource FQCN. The return type is ?array but null is never returned in practice.

```php
public function getResources(): ?array
```

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

### generateForResource(string $resourceKey): void

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Generates all permissions for a given resource FQCN and grants them to the super admin.

```APIDOC
## generateForResource(string $resourceKey): void

### Description
Generates all permissions for a given resource FQCN and grants them to the super admin.

### Method
Static method

### Signature
```php
public static function generateForResource(string $resourceKey): void
```

### Parameters
- **resourceKey** (string) - Required - The fully qualified class name (FQCN) of the resource.

### Behavior
- Creates all permissions for the resource FQCN, then gives them to the super admin.

### Returns
- **void**

### Source
`src/Support/Utils.php:279`
```

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

### Configure Widgets Permissions

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Configuration array for widget permissions. Similar to pages, with 'subject' as 'class', 'prefix' as 'view', and 'exclude' listing AccountWidget and FilamentInfoWidget to skip.

```php
'widgets' => [
    'subject' => 'class',
    'prefix' => 'view',
    'exclude' => [
        \Filament\Widgets\AccountWidget::class,
        \Filament\Widgets\FilamentInfoWidget::class,
    ],
],
```

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

### resolveNamespaceFromPath(string $configuredPath): string

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Maps a filesystem path back to a namespace using the app's composer.json PSR-4 autoload map.

```APIDOC
## resolveNamespaceFromPath(string $configuredPath): string

### Description
Maps a filesystem path back to a namespace using the app's `composer.json` `autoload.psr-4` map (cached in `$psr4Cache`; cacheable via `flushPsr4Cache()`).

### Method
resolveNamespaceFromPath

### Parameters
- **$configuredPath** (string) - Required - The filesystem path to resolve.

### Return Value
- **string** - The namespace, with relative path appended.

### Behavior
- Relative paths resolve against `base_path()`.
- Longest-prefix matching returns `<namespace>\<relative>`.
- Throws `RuntimeException` when no mapping matches: `'Configured path does not match any PSR-4 mapping: <path>'`.
```

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

### Register custom super admin creation closure in boot()

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Use this snippet in a service provider's boot() method to replace Shield's built-in interactive prompts for shield:super-admin. The closure is resolved through the container and must return an Authenticatable instance; returning null falls back to the built-in prompts. It replaces Shield's email and password validation entirely, so validate all collected data and never hardcode credentials. Pair with SuperAdminCommand::prohibit($this->app->isProduction()) to prevent running in production.

```php
use BezhanSalleh\FilamentShield\Commands\SuperAdminCommand;
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Support\Facades\Hash;

use function Laravel\Prompts\password;
use function Laravel\Prompts\text;

public function boot(): void
{
    SuperAdminCommand::createSuperAdminUsing(function (): ?Authenticatable {
        return \App\Models\User::create([
            'name' => text(label: 'First Name', required: true),
            'last_name' => text(label: 'Last Name', required: true),
            'email' => text(
                label: 'Email address',
                required: true,
                validate: fn (string $email): ?string => match (true) {
                    ! filter_var($email, FILTER_VALIDATE_EMAIL) => 'The email address must be valid.',
                    \App\Models\User::where('email', $email)->exists() => 'A user with this email address already exists.',
                    default => null,
                },
            ),
            'password' => Hash::make(password(
                label: 'Password',
                required: true,
                validate: fn (string $value): ?string => match (true) {
                    strlen($value) < 8 => 'The password must be at least 8 characters.',
                    default => null,
                },
            )),
        ]);
    });

    SuperAdminCommand::prohibit($this->app->isProduction());
}
```

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

### createPermission(string $name): string

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Creates a new permission with the given name and the Filament auth guard. Returns the permission name.

```APIDOC
## createPermission(string $name): string

### Description
Creates a new permission with the given name and the Filament auth guard. Returns the permission name.

### Method
Static method

### Signature
```php
public static function createPermission(string $name): string
```

### Parameters
- **name** (string) - Required - The permission name.

### Behavior
- Uses `firstOrCreate(['name' => $name, 'guard_name' => getFilamentAuthGuard()])->name`.

### Returns
- **string** - The name of the created or existing permission.

### Source
`src/Support/Utils.php:250`
```

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

### CanCustomizeColumns: setter method signatures

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

Lists the setter methods for customizing column layouts. All return static and accept int, string, or array parameters.

```php
public function checkboxListColumns(int | string | array $columns): static
public function checkboxListColumnSpan(int | string | array $columnSpan): static
public function gridColumns(int | string | array $columns): static
public function resourceCheckboxListColumns(int | string | array $columns): static
public function resourceCheckboxListColumnSpan(int | string | array $columnSpan): static
public function sectionColumns(int | string | array $columns): static
public function sectionColumnSpan(int | string | array $columnSpan): static
```

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

### Generate Command Options Recap

Source: https://github.com/bezhansalleh/filament-shield/blob/main/README.md

Recap of options for the shield:generate command. Use --all to generate for all discovered entities, --option to override the generator mode, and --resource, --page, --widget to target specific entities. --exclude treats provided entities as exclusions, --ignore-existing-policies skips policies that already exist, --panel is required when not interactive, and --relationships generates tenancy relationships (panel must have tenancy).

```bash
--all  Generate for all discovered entities
--option=policies_and_permissions|policies|permissions|tenant_relationships Override generator mode
--resource=FooResource,BarResource  Target resources (class basenames)
--page=Dashboard,Settings           Target pages (basenames)
--widget=StatsOverview,SalesChart   Target widgets (basenames)
--exclude                           Treat provided entities as exclusions
--ignore-existing-policies          Skip policies whose file already exists, preserving manual edits
--panel=admin                       Panel ID (required when not interactive)
--relationships                     Generate tenancy relationships (panel must have tenancy)
```

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

### toggleEntitiesViaSelectAll(Livewire $livewire, Set $set, bool $state): void

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/traits-form-components.md

Sets each checkbox list to all option keys when state is true, or to an empty array when state is false.

```APIDOC
## toggleEntitiesViaSelectAll

### Description
Sets each checkbox list to all option keys when state is true, or to an empty array when state is false.

### Method
Static helper

### Signature
`public static function toggleEntitiesViaSelectAll(Livewire $livewire, Set $set, bool $state): void`

### Parameters
- **livewire** (Livewire) - Required - The Livewire component instance (aliased import of `Livewire\Component`)
- **set** (Set) - Required - The Filament Set utility (`Filament\Schemas\Components\Utilities\Set`)
- **state** (bool) - Required - If true, sets each list to all option keys; if false, sets each to []
```

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

### Utils::showModelPath

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/support-utils.md

Returns the model path for a given resource if configured, otherwise an empty string.

```APIDOC
## showModelPath(string $resourceFQCN)

### Description
Returns the model path for a given resource if `shield_resource.show_model_path` is enabled, otherwise an empty string.

### Parameters
- **$resourceFQCN** (string) - Required - The fully qualified class name of the resource.

### Returns
- **string** - The model path or empty string.

### Example
```php
use BezhanSalleh\FilamentShield\Support\Utils;

$path = Utils::showModelPath(MyResource::class);
```
```

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

### Utility Methods

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/types.md

Static utility methods for role, permission, and policy management.

```APIDOC
## Utility Methods

### Description
Static methods for creating roles, permissions, and resolving policies.

### createRole
- **Signature**: `Utils::createRole(?string $name = null, int | string | null $tenantId = null): Role`
- **Returns**: `Spatie\Permission\Models\Role` (or configured subclass)

### createPermission
- **Signature**: `Utils::createPermission(string $name): string`
- **Returns**: The permission name

### resolvePolicyFor
- **Signature**: `Utils::resolvePolicyFor(string $model): string`
- **Returns**: Policy FQCN

### resolvePolicyPathFor
- **Signature**: `Utils::resolvePolicyPathFor(string $model): string`
- **Returns**: Policy file path
```

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

### HasPanelShield::canAccessPanel() implementation

Source: https://github.com/bezhansalleh/filament-shield/blob/main/_autodocs/api-reference/traits-entity-shield.md

Super admins always pass; everyone else needs the panel_user role.

```php
if ($this->hasRole(Utils::getSuperAdminName())) {
    return true;
}
return (bool) $this->hasRole(Utils::getPanelUserRoleName());
```
Tokens:
Raw