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

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
`--module=`	Genera permessi per tutti i controller in un modulo specifico	`--module=Shared`, `--module=ContModule`
`--dry-run`	Mostra cosa verrebbe generato senza creare file
`--cleanup`	Rimuove permessi obsoleti per metodi che non esistono più
`--check-conflicts`	Verifica conflitti di naming dei permessi
`--with-policy`	Genera anche le classi Policy per i controller
`--policy-only`	Genera solo le classi Policy senza creare permessi
`--force-policy`	Sovrascrive una Policy esistente (richiede controller specifico, chiede conferma)
`--compact`	Modalità compatta - mostra solo il riepilogo e gli errori
`--skip-admin-assignment`	Non assegna automaticamente i permessi generati al ruolo admin

Esempi di Utilizzo

1. Generazione per Tutti i Controller

php artisan auto-permissions:generate --all

Output di esempio:

🔒 Processing controllers with #[AutoPermissions] attribute

🔍 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
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. Generazione per Modulo Specifico

php artisan auto-permissions:generate --module=Shared

Output di esempio:

🔒 Processing controllers with #[AutoPermissions] attribute

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

📊 Summary: 5 permissions created for Shared

✅ API Permissions generated successfully!

Uso con Policy

Il parametro --module può essere combinato con --with-policy o --policy-only:

php artisan auto-permissions:generate --module=ContModule --with-policy

4. Modalità Compatta

La modalità compatta è ideale per automazione, CI/CD, o quando si vuole un output minimalista:

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

Output di esempio:

📊 Permissions: 1 created, 11 exist
✅ Completed successfully

Con più operazioni:

php artisan auto-permissions:generate --module=Shared --cleanup --compact

Output:

📊 Permissions: 2 created, 8 updated, 10 exist, 1 removed
✅ Completed successfully

Con Policy:

php artisan auto-permissions:generate --all --with-policy --compact

Output:

📊 Permissions: 15 created, 3 exist
🛡️ Policies: 5 generated, 2 skipped
✅ Completed successfully

Quando usare --compact

La modalità compatta è particolarmente utile per:

Pipeline CI/CD: Output pulito nei log di build
Script di automazione: Parsing facile del risultato
Esecuzione frequente: Riduce il rumore visivo
Monitoraggio: Focus solo su statistiche e errori

Mostra sempre gli errori e i conflitti, nasconde solo i dettagli di ogni singola operazione.

5. 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

🔍 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

6. 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

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

7. 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

8. Generazione Policy

Il comando può generare automaticamente le classi Policy per i controller processati.

Permessi + Policy insieme

php artisan auto-permissions:generate --all --with-policy

Output di esempio:

🔒 Processing controllers with #[AutoPermissions] attribute

🔍 Scanning module: Shared (Shared Module)
Processing UserController -> Resource: shared.users
  ✓ Created permission: shared.users.index
  ✓ Created permission: shared.users.show
  ...

📊 Summary: 7 total permissions created

✅ API Permissions generated successfully!

🛡️ Generating Policies...

  ✓ Generated: app/Shared/Policies/UserPolicy.php (7 methods)
  ✓ Generated: app/ContModule/Policies/ContractPolicy.php (5 methods)
  ⏭️ Skipped: DocumentController - Model not found

📊 Policy Summary: 2 generated, 1 skipped

Solo Policy (senza rigenerare permessi)

php artisan auto-permissions:generate --all --policy-only

Sovrascrivere Policy esistenti

php artisan auto-permissions:generate UserController --with-policy --force-policy

Restrizioni --force-policy

Non può essere usato con --all: Per sicurezza, --force-policy richiede di specificare un controller singolo
Richiede conferma: Viene mostrato un prompt di conferma prima di sovrascrivere la Policy esistente
Azione distruttiva: La Policy sovrascritta potrebbe contenere logica custom che verrà persa

Dry Run con Policy

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

Output di esempio:

🔍 DRY RUN MODE - No files will be created

🛡️ Generating Policies...

  ✓ Would generate: app/Shared/Policies/UserPolicy.php (7 methods)
  ⏭️ Skipped: ContractPolicy already exists. Use --force-policy to overwrite

📊 Policy Summary: 1 would be generated, 1 skipped

Policy Generate

Le Policy generate includono:

Metodi standard Laravel: viewAny, view, create, update, delete, restore, forceDelete
Metodi custom: Tutti i metodi pubblici del controller che generano permessi
Commenti: Ogni metodo include un commento che indica quale permesso viene verificato dalla BasePolicy

Vedi la sezione Policy-based Authorization per dettagli sull'uso delle Policy.

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

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

2. Sviluppo per Modulo Specifico

# Lavoro su un modulo specifico
php artisan auto-permissions:generate --module=ContModule --dry-run

# Genera permessi e policy per il modulo
php artisan auto-permissions:generate --module=ContModule --with-policy

# Modalità compatta per output pulito
php artisan auto-permissions:generate --module=Shared --compact

3. Manutenzione Continua

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

# Solo per un modulo specifico
php artisan auto-permissions:generate --module=Shared --cleanup --compact

4. Debug e Troubleshooting

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

# Controlla conflitti su modulo
php artisan auto-permissions:generate --module=ContModule --check-conflicts --dry-run

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

5. Automazione e CI/CD

# Output minimalista per pipeline
php artisan auto-permissions:generate --all --compact

# Verifica e genera con output pulito
php artisan auto-permissions:generate --module=Shared --cleanup --compact

# Genera tutto con policy in modalità compatta
php artisan auto-permissions:generate --all --with-policy --compact

6. 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

Soluzione: Aggiungi #[AutoPermissions] al controller.

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. Generazione per Modulo Specifico​

4. Modalità Compatta​

5. Dry Run (Simulazione)​

6. Cleanup dei Permessi Obsoleti​

7. Controllo Conflitti​

8. Generazione Policy​

Permessi + Policy insieme​

Solo Policy (senza rigenerare permessi)​

Sovrascrivere Policy esistenti​

Dry Run con Policy​

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​

Workflow Raccomandato​

1. Sviluppo Iniziale​

2. Sviluppo per Modulo Specifico​

3. Manutenzione Continua​

4. Debug e Troubleshooting​

5. Automazione e CI/CD​

6. 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. Generazione per Modulo Specifico

4. Modalità Compatta

5. Dry Run (Simulazione)

6. Cleanup dei Permessi Obsoleti

7. Controllo Conflitti

8. Generazione Policy

Permessi + Policy insieme

Solo Policy (senza rigenerare permessi)

Sovrascrivere Policy esistenti

Dry Run con Policy

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

Workflow Raccomandato

1. Sviluppo Iniziale

2. Sviluppo per Modulo Specifico

3. Manutenzione Continua

4. Debug e Troubleshooting

5. Automazione e CI/CD

6. Testing del Sistema di Traduzione

Messaggi di Errore Comuni

Controller non trovato

Attributo mancante

Conflitti di permessi

Best Practices