@mohammadhprp/system-prompt 0.10.1

package/framework/skills/laravel-best-practices/references/spatie-laravel-backup.md

@@ -0,0 +1,222 @@
+# Laravel Backup
+
+## When to Apply
+
+Activate this skill when:
+
+- Configuring backup sources, destinations, or notifications
+- Scheduling backup, cleanup, or monitor commands
+- Creating custom cleanup strategies or health checks
+- Customizing backup notifications
+- Troubleshooting backup failures
+
+## Key Commands
+
+```bash
+
+# Run a backup
+
+php artisan backup:run
+
+# Backup only the database
+
+php artisan backup:run --only-db
+
+# Backup specific database connections
+
+php artisan backup:run --db-name=mysql --db-name=pgsql
+
+# Backup only files (no database)
+
+php artisan backup:run --only-files
+
+# Backup to a specific disk
+
+php artisan backup:run --only-to-disk=s3
+
+# Custom filename
+
+php artisan backup:run --filename=my-backup.zip
+
+# Clean old backups
+
+php artisan backup:clean
+
+# List all backups
+
+php artisan backup:list
+
+# Monitor backup health
+
+php artisan backup:monitor
+
+# Use an alternative config key
+
+php artisan backup:run --config=backup_secondary
+```
+
+## Scheduling
+
+Add to `routes/console.php` or `app/Console/Kernel.php`:
+
+```php
+use Illuminate\Support\Facades\Schedule;
+
+Schedule::command('backup:clean')->daily()->at('01:00');
+Schedule::command('backup:run')->daily()->at('01:30');
+Schedule::command('backup:monitor')->daily()->at('10:00');
+```
+
+## Configuration
+
+Published to `config/backup.php` with sections: `backup` (source files/databases, destination disks, encryption), `notifications` (mail, Slack, Discord), `monitor_backups` (health checks), and `cleanup` (retention strategy).
+
+### Database Dump Customization
+
+Customize dumps per connection in `config/database.php`:
+
+```php
+'mysql' => [
+    // ...
+    'dump' => [
+        'exclude_tables' => ['telescope_entries', 'telescope_monitoring'],
+        'useSingleTransaction' => true,
+    ],
+],
+```
+
+Enable dump compression:
+
+```php
+// config/backup.php
+'database_dump_compressor' => \Spatie\DbDumper\Compressors\GzipCompressor::class,
+```
+
+### Multiple Backup Destinations
+
+```php
+// config/backup.php
+'destination' => [
+    'disks' => ['local', 's3'],
+],
+```
+
+### Encryption
+
+```php
+// config/backup.php
+'password' => env('BACKUP_ARCHIVE_PASSWORD'),
+'encryption' => 'default', // Uses ZipArchive::EM_AES_256
+```
+
+## Custom Cleanup Strategy
+
+Extend `Spatie\Backup\Tasks\Cleanup\CleanupStrategy` and implement `deleteOldBackups`:
+
+```php
+use Spatie\Backup\BackupDestination\BackupCollection;
+use Spatie\Backup\Tasks\Cleanup\CleanupStrategy;
+
+class MyCleanupStrategy extends CleanupStrategy
+{
+    public function deleteOldBackups(BackupCollection $backups): void
+    {
+        $backups
+            ->reject(fn ($backup) => $backup->date()->gt(now()->subMonth()))
+            ->each(fn ($backup) => $backup->delete());
+    }
+}
+```
+
+Register in `config/backup.php`:
+
+```php
+'cleanup' => [
+    'strategy' => \App\Backup\MyCleanupStrategy::class,
+],
+```
+
+## Custom Health Check
+
+Extend `Spatie\Backup\Tasks\Monitor\HealthCheck` and implement `checkHealth`:
+
+```php
+use Spatie\Backup\BackupDestination\BackupDestination;
+use Spatie\Backup\Tasks\Monitor\HealthCheck;
+
+class MinimumBackupCount extends HealthCheck
+{
+    protected int $minimumCount;
+
+    public function __construct(int $minimumCount = 3)
+    {
+        $this->minimumCount = $minimumCount;
+    }
+
+    public function checkHealth(BackupDestination $backupDestination): void
+    {
+        $this->failIf(
+            $backupDestination->backups()->count() < $this->minimumCount,
+            "Expected at least {$this->minimumCount} backups."
+        );
+    }
+}
+```
+
+Register in `config/backup.php`:
+
+```php
+'health_checks' => [
+    \App\Backup\MinimumBackupCount::class => 5,
+],
+```
+
+## Custom Notification
+
+Extend `Spatie\Backup\Notifications\BaseNotification`:
+
+```php
+use Illuminate\Notifications\Messages\MailMessage;
+use Spatie\Backup\Notifications\BaseNotification;
+
+class CustomBackupFailedNotification extends BaseNotification
+{
+    public function toMail(): MailMessage
+    {
+        return (new MailMessage)
+            ->error()
+            ->subject("Backup failed for {$this->applicationName()}")
+            ->line($this->event->exception->getMessage());
+    }
+}
+```
+
+Map it in `config/backup.php`:
+
+```php
+'notifications' => [
+    'notifications' => [
+        \App\Notifications\CustomBackupFailedNotification::class => ['mail'],
+    ],
+],
+```
+
+## Events
+
+All events are in `Spatie\Backup\Events`:
+
+- `BackupWasSuccessful` - Backup completed successfully
+- `BackupHasFailed` - Backup failed (includes exception and optional backup destination)
+- `BackupManifestWasCreated` - File manifest created before zipping
+- `BackupZipWasCreated` - Zip archive created (used for encryption hook)
+- `DumpingDatabase` - Database dump in progress
+- `CleanupWasSuccessful` / `CleanupHasFailed` - Cleanup result
+- `HealthyBackupWasFound` / `UnhealthyBackupWasFound` - Monitor result
+
+## Common Pitfalls
+
+- Forgetting to schedule `backup:clean` alongside `backup:run`, causing disk space to fill up
+- Not excluding `vendor` and `node_modules` from file backups (excluded by default)
+- Setting `only-db` and `only-files` together (mutually exclusive)
+- Missing the `ext-zip` PHP extension
+- Not configuring the notification `mail.to` address after publishing config

package/framework/skills/laravel-best-practices/references/spatie-laravel-permission.md

@@ -0,0 +1,272 @@
+# Laravel Permission Development
+
+## When to use this skill
+
+Use this skill when working with authorization, roles, permissions, access control, middleware guards, or Blade permission directives using spatie/laravel-permission.
+
+## Core Concepts
+
+- **Users have Roles, Roles have Permissions, Apps check Permissions** (not Roles).
+- Direct permissions on users are an anti-pattern; assign permissions to roles instead.
+- Use `$user->can('permission-name')` for all authorization checks (supports Super Admin via Gate).
+- The `HasRoles` trait (which includes `HasPermissions`) is added to User models.
+
+## Setup
+
+Add the `HasRoles` trait to your User model:
+
+```php
+use Spatie\Permission\Traits\HasRoles;
+
+class User extends Authenticatable
+{
+    use HasRoles;
+}
+```
+
+## Creating Roles and Permissions
+
+```php
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\Models\Permission;
+
+$role = Role::create(['name' => 'writer']);
+$permission = Permission::create(['name' => 'edit articles']);
+
+// findOrCreate is idempotent (safe for seeders)
+$role = Role::findOrCreate('writer', 'web');
+$permission = Permission::findOrCreate('edit articles', 'web');
+```
+
+## Assigning Roles and Permissions
+
+```php
+// Assign roles to users
+$user->assignRole('writer');
+$user->assignRole('writer', 'admin');
+$user->assignRole(['writer', 'admin']);
+$user->syncRoles(['writer', 'admin']); // replaces all
+$user->removeRole('writer');
+
+// Assign permissions to roles (preferred)
+$role->givePermissionTo('edit articles');
+$role->givePermissionTo(['edit articles', 'delete articles']);
+$role->syncPermissions(['edit articles', 'delete articles']);
+$role->revokePermissionTo('edit articles');
+
+// Reverse assignment
+$permission->assignRole('writer');
+$permission->syncRoles(['writer', 'editor']);
+$permission->removeRole('writer');
+```
+
+## Checking Roles and Permissions
+
+```php
+// Permission checks (preferred - supports Super Admin via Gate)
+$user->can('edit articles');
+$user->canAny(['edit articles', 'delete articles']);
+
+// Direct package methods (bypass Gate, no Super Admin support)
+$user->hasPermissionTo('edit articles');
+$user->hasAnyPermission(['edit articles', 'publish articles']);
+$user->hasAllPermissions(['edit articles', 'publish articles']);
+$user->hasDirectPermission('edit articles');
+
+// Role checks
+$user->hasRole('writer');
+$user->hasAnyRole(['writer', 'editor']);
+$user->hasAllRoles(['writer', 'editor']);
+$user->hasExactRoles(['writer', 'editor']);
+
+// Get assigned roles and permissions
+$user->getRoleNames();           // Collection of role name strings
+$user->getPermissionNames();     // Collection of permission name strings
+$user->getDirectPermissions();   // Direct permissions only
+$user->getPermissionsViaRoles(); // Inherited via roles
+$user->getAllPermissions();      // Both direct and inherited
+```
+
+## Query Scopes
+
+```php
+$users = User::role('writer')->get();
+$users = User::withoutRole('writer')->get();
+$users = User::permission('edit articles')->get();
+$users = User::withoutPermission('edit articles')->get();
+```
+
+## Middleware
+
+Register middleware aliases in `bootstrap/app.php`:
+
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->alias([
+        'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
+        'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
+        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
+    ]);
+})
+```
+
+Use in routes (pipe `|` for OR logic):
+
+```php
+Route::middleware(['permission:edit articles'])->group(function () { ... });
+Route::middleware(['role:manager|writer'])->group(function () { ... });
+Route::middleware(['role_or_permission:manager|edit articles'])->group(function () { ... });
+
+// With specific guard
+Route::middleware(['role:manager,api'])->group(function () { ... });
+```
+
+For single permissions, Laravel's built-in `can` middleware also works:
+
+```php
+Route::middleware(['can:edit articles'])->group(function () { ... });
+```
+
+## Blade Directives
+
+Prefer `@can` (permission-based) over `@role` (role-based):
+
+```blade
+@can('edit articles')
+    {{-- User can edit articles (supports Super Admin) --}}
+@endcan
+
+@canany(['edit articles', 'delete articles'])
+    {{-- User can do at least one --}}
+@endcanany
+
+@role('admin')
+    {{-- Only use for super-admin type checks --}}
+@endrole
+
+@hasanyrole('writer|admin')
+    {{-- Has writer or admin --}}
+@endhasanyrole
+```
+
+## Super Admin
+
+Use `Gate::before` in `AppServiceProvider::boot()`:
+
+```php
+use Illuminate\Support\Facades\Gate;
+
+public function boot(): void
+{
+    Gate::before(function ($user, $ability) {
+        return $user->hasRole('Super Admin') ? true : null;
+    });
+}
+```
+
+This makes `$user->can()` and `@can` always return true for Super Admins. Must return `null` (not `false`) to allow normal checks for other users.
+
+## Policies
+
+Use `$user->can()` inside policy methods to check permissions:
+
+```php
+class PostPolicy
+{
+    public function update(User $user, Post $post): bool
+    {
+        if ($user->can('edit all posts')) {
+            return true;
+        }
+
+        return $user->can('edit own posts') && $user->id === $post->user_id;
+    }
+}
+```
+
+## Enums
+
+```php
+enum RolesEnum: string
+{
+    case WRITER = 'writer';
+    case EDITOR = 'editor';
+}
+
+enum PermissionsEnum: string
+{
+    case EDIT_POSTS = 'edit posts';
+    case DELETE_POSTS = 'delete posts';
+}
+
+// Creation requires ->value
+Permission::findOrCreate(PermissionsEnum::EDIT_POSTS->value, 'web');
+
+// Most methods accept enums directly
+$user->assignRole(RolesEnum::WRITER);
+$user->hasRole(RolesEnum::WRITER);
+$role->givePermissionTo(PermissionsEnum::EDIT_POSTS);
+$user->hasPermissionTo(PermissionsEnum::EDIT_POSTS);
+```
+
+## Seeding
+
+Always flush the permission cache when seeding:
+
+```php
+class RolesAndPermissionsSeeder extends Seeder
+{
+    public function run(): void
+    {
+        // Reset cache
+        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
+
+        // Create permissions
+        Permission::findOrCreate('edit articles', 'web');
+        Permission::findOrCreate('delete articles', 'web');
+
+        // Create roles and assign permissions
+        Role::findOrCreate('writer', 'web')
+            ->givePermissionTo(['edit articles']);
+
+        Role::findOrCreate('admin', 'web')
+            ->givePermissionTo(Permission::all());
+    }
+}
+```
+
+## Teams (Multi-Tenancy)
+
+Enable in `config/permission.php` before running migrations:
+
+```php
+'teams' => true,
+```
+
+Set the active team in middleware:
+
+```php
+setPermissionsTeamId($teamId);
+```
+
+When switching teams, unset cached relations:
+
+```php
+$user->unsetRelation('roles')->unsetRelation('permissions');
+```
+
+## Events
+
+Enable in `config/permission.php`:
+
+```php
+'events_enabled' => true,
+```
+
+Available events: `RoleAttachedEvent`, `RoleDetachedEvent`, `PermissionAttachedEvent`, `PermissionDetachedEvent` in the `Spatie\Permission\Events` namespace.
+
+## Performance
+
+- Permissions are cached automatically. The cache is flushed when roles/permissions change via package methods.
+- After direct DB operations, flush manually: `app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions()`
+- For bulk seeding, use `Permission::insert()` for speed, but flush the cache afterward.