README

A filament plugin that provides tenant, user, permission and role management simply by installing it

Cardinal

This plugin is highly experimental it is not recommended to use in a production app yet. There is a lot of configuration that is still hardcoded and translations are not setup yet

Setup & Configuration

New Larvel installation (or existing at own risk)

Follow the Laravel Create Project instructions
Install Filament & Panel Builder

Follow the Filament Installation instructions
Delete Migrations

The plugin has the following migrations already setup:
- create_cache_table
- create_jobs_table
- create_tenants_table
- create_roles_table
- create_users_table
- create_tenant_user_table
- create_role_user_table
In a new project that means you need to delete the users, cache, jobs migrations
Delete User Model

The plugin provides a ready to use user model. So you can delete the default one.
Update User model in auth config

Laravel needs to know where the user model is located so inside the config/auth.php file search for this line

'model' => env('AUTH_MODEL', App\Models\User::class),

and replace the user model class like this

'model' => env('AUTH_MODEL', \DevIdkwhoami\Cardinal\Models\User::class),
Create filament theme

Use the following command to create a theme for the cardinal panel
```
 php artisan make:filament-theme cardinal-admin
```
Migrate database

Migrate the database using
```
 php artisan migreate:fresh
```
Optionally add the following code in your database seeder:
```
 CardinalPlugin::repository()->seed();
```
to get example data.

WIP: Massasignment guard

For now you ahve to do Model::unguard() for the resources to work properly

How to use

Prepare your filament panel like you are used to. Then require the plugin through composer

composer require dev-idkwhoami/cardinal

After it is done installing you can add the plugin to your panel using the ->plugins() function.


use DevIdkwhoami\Cardinal\CardinalPlugin;
use DevIdkwhoami\Cardinal\CardinalRepository;

CardinalPlugin::make(function (CardinalRepository $repository) {
    $repository
        /* Only models registered thorugh this function will be handled by the plugin */
        ->models([
            Book::class,
        ])
        ->modelAbilities([
            'users.delete' => fn (User $user, Model $model) => ! $model->is($user),
        ])
        ->permissions([
            PermissionGroup::make('app', 'Application')
                ->weight(99)
                ->permissions([
                    Permission::make('access'),
                ]),
        ]);
})
->dontRunMigrations()
->cardinalPanelId("Something other than Cardinal")
->tenancy();

Here an example of a model setup to be handled by the plugin:

class Book extends Model
{
    /* BelongsToTenant ensures this model uses tenancy */
    /* HasPermissions ensures this models abilities are registered and handled automatically */
    use BelongsToTenant, HasFactory, HasPermissions, HasUlids, SoftDeletes;

    protected $fillable = [
        'title',
        'description',
    ];

}

Plugin

The CardinalPlugin is the entry point of the plugin. It provides you with the functions to majorly change the plugins behavior.

Functions

    ->dontRunMigrations() // prevents the plugin from running its migrations by itself
    ->cardinalPanelId("Something other than Cardinal") // sets the panel id of the internal CardinalPanel
    ->tenancy() // enables tenancy on the panel (make sure your models are prepared)

Repository

The CardinalRepository is an object that keeps all the information registered by different panels. It provides you with the functions to register models and permissions.

Functions

    ->models([...]) // registers your models with the plugin
    ->modelAbilities([...]) // allows you to implement custom permission logic for "magic permissions"
    ->permissions([...]) // registers custom permissions with the plugin

PermissionGroups and Permissions

When registering the plugin on the panel generally you don't need to register any permissions if you use the HasPermissions trait on the model and add it to the ->models() array But if you want to register extra permissions for any reason this is how you can do it

All permissions require a permission group to create one use do this:

use \DevIdkwhoami\Cardinal\Authorization\PermissionGroup;

PermissionGroup::make('extra')
    ->permissions([
        // ...
    ])

The make() function takes more arguments than just the group key:

key is the permission groups unique prefix
name is used as labels on the PermissionTabs form block
weight is used for sorting the tabs on the PermissionTabs form block
description give you the option to add more detail to a permission

use \DevIdkwhoami\Cardinal\Authorization\PermissionGroup;

PermissionGroup::make('extra', 'A Name For Displaying', 42, "A description for more information")
    ->permissions([
        // ...
    ])

Now to create a permission you go like this:

use \DevIdkwhoami\Cardinal\Authorization\PermissionGroup;
use \DevIdkwhoami\Cardinal\Authorization\Permission;

PermissionGroup::make('extra', 'A Name For Displaying', 42, "A description for more information")
    ->permissions([
        Permission::make('supersecrect'),
    ])

The make() function here also takes the same arguments as on the permission gruop

Traits

This plugin uses traits to handle permissions, tenancy, etc.

BelongsToTenant

This trait adds a tenant() relationship to the model (make sure to add a tenant_id column in your migration)
HasPermissions

A model with this trait will be picked up by the permission system to be handled automatically, the default filament abilities are made available as permissions
HoldsPermissions

A model with this trait can hold permissions (make sure to add a permissions json column to your migration)
MutatesPermissions

Any page that uses the PermissionTabs form block needs add this trait it ensures the permissions are combined into the permissions column and formatted correctly including combining "all permissions" of one group to be shortened into group.*

Form & Table Blocks

This plugin provides a bunch of prebuilt blocks to reuse.

Form Blocks

PanelsAccessList

This block provides a section or a pre-configured Checkboxlist for granting access to panels. This component expects a panels json column on the model
PermissionTabs

This block provides a tab section for granting permissions registered through the plugin. This component expects a permissions json column on the model
RolesList

This block provides a section or a pre-configured Checkboxlist for granting roles. This component expects a roles relationship on the model
TenantsList

This block provides a section or a pre-configured Checkboxlist for assigning users to tenants. This component expects a tenants relationship on the model
TimestampBlock

This block provides a fieldset or a pre-configured set of datetime fields to have a uniform way of displaying model timestamps (created_at, updated_at, deleted_at)

Table Blocks

TimestampColumns

This block provides a pre-configured set of datetime columns to have a uniform way of displaying model timestamps (created_at, updated_at, deleted_at)

dev-idkwhoami / cardinal

Maintainers

Details

README

Setup & Configuration

How to use

Plugin

Functions

Repository

Functions

PermissionGroups and Permissions

Traits

Form & Table Blocks

Form Blocks

Table Blocks