Comandi AutoPermissions

Il sistema AutoPermissions fornisce potenti comandi Artisan per gestire la generazione, cache e manutenzione dei permessi. Questa sezione documenta tutti i comandi disponibili con esempi pratici e output di esempio.

Panoramica Comandi

Comando	Scopo	Uso Principale
`auto-permissions:generate`	Genera permessi dai controller	Creazione e manutenzione permessi
`auto-permissions:update-titles`	Aggiorna titoli permessi esistenti	Testing locale e standardizzazione titoli
`auto-permissions:cache`	Gestisce cache del sistema	Ottimizzazione prestazioni

Comando: `auto-permissions:generate`

Il comando principale per generare i permessi dai controller configurati con AutoPermissions.

Sintassi Completa

php artisan auto-permissions:generate [controller] [options]

Parametri e Opzioni

Parametro/Opzione	Descrizione	Esempio
`controller`	Nome specifico del controller da processare	`Shared\\Users\\UserController`
`--all`	Genera permessi per tutti i controller in tutti i moduli
`--dry-run`	Mostra cosa verrebbe generato senza creare permessi
`--cleanup`	Rimuove permessi obsoleti per metodi che non esistono più
`--check-conflicts`	Verifica conflitti di naming dei permessi

Esempi di Utilizzo

1. Generazione per Tutti i Controller

php artisan auto-permissions:generate --all

Output di esempio:

🔒 Processing controllers with AutoPermissions attribute or HasAutoPermissionsTrait

🔍 Scanning module: Shared (Shared Module)
Processing UserController -> Resource: shared.users
  ✓ Created permission: shared.users.index
  ✓ Created permission: shared.users.create
  ✓ Created permission: shared.users.store
  ✓ Created permission: shared.users.show
  ✓ Created permission: shared.users.edit
  ✓ Created permission: shared.users.update
  ✓ Created permission: shared.users.destroy
  📋 Shared: 7 permissions

🔍 Scanning module: ContModule (Contracts Module)
Processing ContractController -> Resource: cont.contracts
  ✓ Created permission: cont.contracts.index
  ✓ Created permission: cont.contracts.create
  ✓ Created permission: cont.contracts.store
  📋 ContModule: 3 permissions

📊 Summary: 10 total permissions created

✅ API Permissions generated successfully!

🔍 Conflict Detection:
// Check only for conflicts (no generation):
php artisan auto-permissions:generate --all --check-conflicts --dry-run
// Check conflicts AND generate permissions:
php artisan auto-permissions:generate --all --check-conflicts

2. Generazione per Controller Specifico

php artisan auto-permissions:generate UserController

Output di esempio:

🔒 Processing controllers with AutoPermissions attribute or HasAutoPermissionsTrait
Processing UserController -> Resource: shared.users
  ✓ Created permission: shared.users.index
  ✓ Created permission: shared.users.create
  ✓ Created permission: shared.users.store
  ✓ Created permission: shared.users.show
  ✓ Created permission: shared.users.edit
  ✓ Created permission: shared.users.update
  ✓ Created permission: shared.users.destroy

✅ API Permissions generated successfully!

3. Dry Run (Simulazione)

php artisan auto-permissions:generate --all --dry-run

Output di esempio:

🔍 DRY RUN MODE - No permissions will be created
🔒 Processing controllers with AutoPermissions attribute or HasAutoPermissionsTrait

🔍 Scanning module: Shared (Shared Module)
Processing UserController -> Resource: shared.users
  ✓ Would create permission: shared.users.index
  ✓ Would create permission: shared.users.create
  ✓ Would create permission: shared.users.store

📊 Summary: 3 total permissions would be created

4. Cleanup dei Permessi Obsoleti

php artisan auto-permissions:generate --all --cleanup

Output di esempio:

🧹 CLEANUP MODE - Obsolete permissions will be removed
🔒 Processing controllers with AutoPermissions attribute or HasAutoPermissionsTrait

Processing UserController -> Resource: shared.users
  ✓ Created permission: shared.users.index
  ✓ Created permission: shared.users.create
  🗑️ Removed obsolete permission: shared.users.oldMethod
  🧹 Cleaned up 1 obsolete permissions for shared.users

📊 Summary: 2 total permissions created

5. Controllo Conflitti

php artisan auto-permissions:generate --all --check-conflicts --dry-run

Output di esempio con conflitti:

⚠️  CONFLICT CHECK MODE - Checking for permission conflicts
🔍 DRY RUN MODE - No permissions will be created

⚠️  PERMISSION CONFLICTS DETECTED!
The following permissions are generated by multiple controllers:

🔥 Permission: shared.users.index
   Generated by:
     • App\Shared\Http\Controllers\UserController -> index()
     • App\Shared\Http\Controllers\Admin\UserController -> index()

💡 Solutions:
1. Use #[PermissionNaming] attribute to specify unique resource names
2. Use #[CustomPermission] attribute on methods to specify unique permissions
3. Restructure controllers to avoid naming conflicts
4. Use sub-namespaces in permission names (e.g., "admin.users" vs "api.users")

Total conflicts: 1

Comando: `auto-permissions:update-titles`

Aggiorna i titoli dei permessi esistenti per un controller specifico basandosi sugli attributi CustomPermission o sulla generazione automatica.

Attenzione - Sovrascrittura Titoli

Questo comando sovrascrive eventuali titoli modificati manualmente nel database. È progettato principalmente per testare in locale la generazione automatica dei titoli e verificare il funzionamento del sistema di traduzione.

Sintassi

php artisan auto-permissions:update-titles {module} {controller} [options]

Parametri

Parametro	Descrizione	Esempio
`module`	Nome breve del modulo (es. shared, ago, bt, cont)	`shared`
`controller`	Nome o percorso del controller specifico	`UserController`, `Users/UserController`, `Users\\SharedUser`
`--dry-run`	Mostra cosa verrebbe aggiornato senza apportare modifiche

Come Funziona la Generazione Automatica dei Titoli

Il sistema genera automaticamente i titoli dei permessi combinando:

Azione tradotta: Dal file lang/it/permissions.php sezione actions
Risorsa tradotta: Dal file lang/it/permissions.php sezione resources
Logica singolare/plurale: Basata sui metodi definiti in plural_methods

Formato del Titolo Generato

{Azione} {Risorsa}

Esempi:

shared.users.index → "Elenco utenti" (plurale per index)
shared.users.show → "Visualizzare utente" (singolare per show)
shared.users.create → "Creare utente" (singolare per create)
shared.users.destroy → "Eliminare utente" (singolare per destroy)

File di Traduzione (`lang/it/permissions.php`)

Il file contiene tre sezioni principali:

// Traduzioni delle azioni (verbi)
'actions' => [
    'index' => 'Elenco',
    'show' => 'Visualizzare',
    'create' => 'Creare',
    'store' => 'Aggiungere',
    'edit' => 'Modificare',
    'update' => 'Modificare',
    'destroy' => 'Eliminare',
    // ...
],

// Traduzioni delle risorse (sostantivi)
'resources' => [
    'users' => 'utenti',      // plurale
    'user' => 'utente',       // singolare
    'companies' => 'aziende', // plurale
    'company' => 'azienda',   // singolare
    // ...
],

// Metodi che richiedono la forma plurale
'plural_methods' => [
    'index', 'export', 'import',
],

Esempi di Utilizzo

1. Dry Run (Simulazione)

php artisan auto-permissions:update-titles shared UserController --dry-run

Output di esempio:

🔍 DRY RUN MODE - No titles will be updated
🔄 Updating permission titles for existing permissions
Module: shared (Shared)
Processing UserController -> Resource: shared.users
  Would update title: shared.users.index
    From: (no title)
    To:   Elenco utenti
  Would update title: shared.users.show
    From: View User
    To:   Visualizzare utente
  ✓ No change needed: shared.users.create

2. Aggiornamento Effettivo

php artisan auto-permissions:update-titles shared UserController

Output con conferma richiesta:

⚠️  WARNING: TITLE UPDATE MODE ACTIVE
This procedure will update permission titles and may overwrite manually set titles.
It is recommended to use --dry-run first to preview changes.
You are about to update permission titles for existing permissions.

Are you sure you want to proceed with updating permission titles? (yes/no) [no]:
> yes

Proceeding with permission title updates...
🔄 Updating permission titles for existing permissions
Module: shared (Shared)
Processing UserController -> Resource: shared.users
  Updated title: shared.users.index
    From: (no title)
    To:   Elenco utenti
  Updated title: shared.users.show
    From: View User
    To:   Visualizzare utente

✅ Permission titles updated successfully!

3. Controller con Percorso Completo

php artisan auto-permissions:update-titles shared Users/UserController --dry-run

4. Controller con Attributi CustomPermission

Se un metodo ha l'attributo #[CustomPermission] con un titolo personalizzato:

#[CustomPermission(action: 'manage_profile', title: 'Gestire profilo utente')]
public function updateProfile() { }

Il comando userà il titolo personalizzato invece della generazione automatica.

Priorità nella Generazione del Titolo

Titolo CustomPermission: Se presente nell'attributo #[CustomPermission(title: '...')]
Generazione Automatica: Basata su traduzione azione + risorsa
Fallback: Se non trova traduzioni, mantiene il titolo esistente

Caso d'Uso Principale

Questo comando è principalmente destinato allo sviluppo e testing locale per:

Verificare traduzioni: Testare che le nuove voci in permissions.php funzionino correttamente
Debug del sistema: Identificare permessi con traduzioni mancanti
Reset dopo modifiche manuali: Ripristinare i titoli automatici dopo modifiche manuali al DB

Workflow Consigliato

Aggiungi nuove traduzioni in lang/it/permissions.php
Usa --dry-run per verificare i risultati
Esegui l'aggiornamento effettivo solo se soddisfatto
In produzione, i titoli vengono generati automaticamente alla creazione dei permessi

Comando: `auto-permissions:cache`

Gestisce la cache del sistema AutoPermissions per ottimizzare le prestazioni.

Sintassi

php artisan auto-permissions:cache [action]

Azioni Disponibili

Azione	Descrizione
`build`	Costruisce la cache processando tutte le route (default)
`clear`	Cancella completamente la cache
`status`	Mostra lo stato attuale della cache

Esempi di Utilizzo

1. Costruire la Cache

php artisan auto-permissions:cache build

Output di esempio:

Building permission cache...
🔒 Processing controllers with AutoPermissions attribute or HasAutoPermissionsTrait
  ✓ api.shared.users.index -> shared.users.index (key: route_permissions_api_shared_users_index)
  ✓ api.shared.users.create -> shared.users.create (key: route_permissions_api_shared_users_create)
  ✓ api.shared.users.store -> shared.users.store (key: route_permissions_api_shared_users_store)
  ✓ api.cont.contracts.index -> cont.contracts.index (key: route_permissions_api_cont_contracts_index)

Cache built successfully!
Cached: 15 routes
Skipped: 23 routes

2. Cancellare la Cache

php artisan auto-permissions:cache clear

Output di esempio:

Clearing permission cache...
✓ Cache cleared using tags
Permission cache cleared successfully!

Output per cache driver senza supporto tag:

Clearing permission cache...
Cache tags not supported, clearing manually...
  ✓ Cleared key: route_permissions_api_shared_users_index
  ✓ Cleared key: route_permissions_api_shared_users_create
  ✓ Cleared key: route_permissions_api_cont_contracts_index
✓ Manually cleared 15 cache entries
Permission cache cleared successfully!

3. Stato della Cache

php artisan auto-permissions:cache status

Output di esempio:

Permission Cache Status:
🔒 Analyzing controllers with AutoPermissions attribute or HasAutoPermissionsTrait
Total eligible routes: 15
Cached routes: 12
Cache coverage: 80.00%
Consider running 'php artisan auto-permissions:cache build' to improve performance

Workflow Raccomandato

1. Sviluppo Iniziale

# 1. Aggiungi attributi ai controller
# 2. Verifica cosa verrà generato
php artisan auto-permissions:generate --all --dry-run

# 3. Controlla possibili conflitti
php artisan auto-permissions:generate --all --check-conflicts --dry-run

# 4. Genera i permessi
php artisan auto-permissions:generate --all

# 5. Costruisci la cache per prestazioni
php artisan auto-permissions:cache build

2. Manutenzione Continua

# Dopo modifiche ai controller
php artisan auto-permissions:generate --all --cleanup

# Ricostruire cache dopo modifiche
php artisan auto-permissions:cache build

3. Debug e Troubleshooting

# Verifica stato cache
php artisan auto-permissions:cache status

# Controlla conflitti su controller specifico
php artisan auto-permissions:generate UserController --check-conflicts --dry-run

# Simula cleanup senza modifiche
php artisan auto-permissions:generate --all --cleanup --dry-run

4. Testing del Sistema di Traduzione

# Verifica traduzioni per un controller specifico
php artisan auto-permissions:update-titles shared UserController --dry-run

# Aggiorna titoli dopo modifiche al file permissions.php
php artisan auto-permissions:update-titles shared UserController

Messaggi di Errore Comuni

Controller non trovato

Controller 'UserController' not found in any module

Soluzione: Verifica il nome del controller e che esista nel namespace corretto.

Attributo mancante

⏭️  Skipping UserController - missing AutoPermissions attribute and HasAutoPermissionsTrait

Soluzione: Aggiungi #[AutoPermissions] al controller o il trait HasAutoPermissionsTrait.

Conflitti di permessi

⚠️  PERMISSION CONFLICTS DETECTED!

Soluzione: Usa #[PermissionNaming] o #[CustomPermission] per risolvere i conflitti.

Best Practices

Sempre dry-run prima: Usa --dry-run per verificare le modifiche
Controlla conflitti: Usa --check-conflicts prima della generazione
Cleanup regolare: Usa --cleanup per rimuovere permessi obsoleti
Cache management: Ricostruisci la cache dopo modifiche importanti
Monitoring: Controlla regolarmente lo stato della cache con status
Testing titoli: Usa update-titles --dry-run per testare traduzioni in locale

Panoramica Comandi​

Comando: auto-permissions:generate​

Sintassi Completa​

Parametri e Opzioni​

Esempi di Utilizzo​

1. Generazione per Tutti i Controller​

2. Generazione per Controller Specifico​

3. Dry Run (Simulazione)​

4. Cleanup dei Permessi Obsoleti​

5. Controllo Conflitti​

Comando: auto-permissions:update-titles​

Sintassi​

Parametri​

Come Funziona la Generazione Automatica dei Titoli​

Formato del Titolo Generato​

File di Traduzione (lang/it/permissions.php)​

Esempi di Utilizzo​

1. Dry Run (Simulazione)​

2. Aggiornamento Effettivo​

3. Controller con Percorso Completo​

4. Controller con Attributi CustomPermission​

Priorità nella Generazione del Titolo​

Caso d'Uso Principale​

Comando: auto-permissions:cache​

Sintassi​

Azioni Disponibili​

Esempi di Utilizzo​

1. Costruire la Cache​

2. Cancellare la Cache​

3. Stato della Cache​

Workflow Raccomandato​

1. Sviluppo Iniziale​

2. Manutenzione Continua​

3. Debug e Troubleshooting​

4. Testing del Sistema di Traduzione​

Messaggi di Errore Comuni​

Controller non trovato​

Attributo mancante​

Conflitti di permessi​

Best Practices​

Panoramica Comandi

Comando: `auto-permissions:generate`

Sintassi Completa

Parametri e Opzioni

Esempi di Utilizzo

1. Generazione per Tutti i Controller

2. Generazione per Controller Specifico

3. Dry Run (Simulazione)

4. Cleanup dei Permessi Obsoleti

5. Controllo Conflitti

Comando: `auto-permissions:update-titles`

Sintassi

Parametri

Come Funziona la Generazione Automatica dei Titoli

Formato del Titolo Generato

File di Traduzione (`lang/it/permissions.php`)

Esempi di Utilizzo

1. Dry Run (Simulazione)

2. Aggiornamento Effettivo

3. Controller con Percorso Completo

4. Controller con Attributi CustomPermission

Priorità nella Generazione del Titolo

Caso d'Uso Principale

Comando: `auto-permissions:cache`

Sintassi

Azioni Disponibili

Esempi di Utilizzo

1. Costruire la Cache

2. Cancellare la Cache

3. Stato della Cache

Workflow Raccomandato

1. Sviluppo Iniziale

2. Manutenzione Continua

3. Debug e Troubleshooting

4. Testing del Sistema di Traduzione

Messaggi di Errore Comuni

Controller non trovato

Attributo mancante

Conflitti di permessi

Best Practices