bhoza-shift-manager/docs/filament-admin.md

# Filament Admin Panel

This template includes optional [Filament](https://filamentphp.com/) admin panel setup for user management and administration.

## What is Filament?

Filament is a full-stack admin panel framework for Laravel built on Livewire. It provides:

- **Admin Panel** - Beautiful, responsive dashboard
- **Form Builder** - Dynamic forms with validation
- **Table Builder** - Sortable, searchable, filterable tables
- **User Management** - CRUD for users out of the box
- **Widgets** - Dashboard stats and charts
- **Notifications** - Toast notifications
- **Actions** - Bulk actions, row actions

## Installation

Filament is installed via `make setup-laravel` when you select "Yes" for admin panel.

Manual installation:

```bash
composer require filament/filament:"^3.2" -W
php artisan filament:install --panels
php artisan make:filament-user
php artisan make:filament-resource User --generate
```

## Accessing Admin Panel

- **URL**: `http://localhost:8080/admin`
- **Login**: Use credentials created during setup

## User Management

The setup creates a `UserResource` at `app/Filament/Resources/UserResource.php`.

This provides:
- List all users with search/filter
- Create new users
- Edit existing users
- Delete users

### Customizing User Resource

Edit `app/Filament/Resources/UserResource.php`:

```php
public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('name')
                ->required()
                ->maxLength(255),
            Forms\Components\TextInput::make('email')
                ->email()
                ->required()
                ->unique(ignoreRecord: true),
            Forms\Components\DateTimePicker::make('email_verified_at'),
            Forms\Components\TextInput::make('password')
                ->password()
                ->dehydrateStateUsing(fn ($state) => Hash::make($state))
                ->dehydrated(fn ($state) => filled($state))
                ->required(fn (string $context): bool => $context === 'create'),
        ]);
}

public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('name')
                ->searchable(),
            Tables\Columns\TextColumn::make('email')
                ->searchable(),
            Tables\Columns\TextColumn::make('email_verified_at')
                ->dateTime()
                ->sortable(),
            Tables\Columns\TextColumn::make('created_at')
                ->dateTime()
                ->sortable()
                ->toggleable(isToggledHiddenByDefault: true),
        ])
        ->filters([
            //
        ])
        ->actions([
            Tables\Actions\EditAction::make(),
            Tables\Actions\DeleteAction::make(),
        ])
        ->bulkActions([
            Tables\Actions\BulkActionGroup::make([
                Tables\Actions\DeleteBulkAction::make(),
            ]),
        ]);
}
```

## Adding Roles & Permissions

For role-based access, add Spatie Permission:

```bash
composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan migrate
```

Then install Filament Shield for admin UI:

```bash
composer require bezhansalleh/filament-shield
php artisan shield:install
```

This adds:
- Role management in admin
- Permission management
- Protect resources by role

## Creating Additional Resources

```bash
# Generate resource for a model
php artisan make:filament-resource Post --generate

# Generate with soft deletes
php artisan make:filament-resource Post --generate --soft-deletes

# Generate simple (modal-based, no separate pages)
php artisan make:filament-resource Post --simple
```

## Dashboard Widgets

Create a stats widget:

```bash
php artisan make:filament-widget StatsOverview --stats-overview
```

Edit `app/Filament/Widgets/StatsOverview.php`:

```php
protected function getStats(): array
{
    return [
        Stat::make('Total Users', User::count()),
        Stat::make('Verified Users', User::whereNotNull('email_verified_at')->count()),
        Stat::make('New Today', User::whereDate('created_at', today())->count()),
    ];
}
```

## Restricting Admin Access

### By Email Domain

In `app/Providers/Filament/AdminPanelProvider.php`:

```php
->authGuard('web')
->login()
->registration(false) // Disable public registration
```

### By User Method

Add to `User` model:

```php
public function canAccessPanel(Panel $panel): bool
{
    return str_ends_with($this->email, '@yourcompany.com');
}
```

Or with roles:

```php
public function canAccessPanel(Panel $panel): bool
{
    return $this->hasRole('admin');
}
```

## Customizing Theme

Publish and customize:

```bash
php artisan vendor:publish --tag=filament-config
php artisan vendor:publish --tag=filament-panels-translations
```

Edit colors in `app/Providers/Filament/AdminPanelProvider.php`:

```php
->colors([
    'primary' => Color::Indigo,
    'danger' => Color::Rose,
    'success' => Color::Emerald,
])
```

## Production Considerations

1. **Disable registration** in admin panel
2. **Use strong passwords** for admin users
3. **Enable 2FA** if using Jetstream
4. **Restrict by IP** in production if possible
5. **Monitor admin actions** via activity logging

## Resources

- [Filament Documentation](https://filamentphp.com/docs)
- [Filament Plugins](https://filamentphp.com/plugins)
- [Filament Shield (Roles)](https://github.com/bezhanSalleh/filament-shield)