Best practices

Convenzioni

Laravel segue una serie di convenzioni di naming ben definite che aiutano a mantenere il codice organizzato e prevedibile. Seguire queste convenzioni è importante per:

• Mantenere consistenza nel codebase
• Facilitare la comprensione del codice da parte di altri sviluppatori
• Sfruttare le funzionalità di auto-loading e service container
• Seguire le best practices della community

Cheat Sheet Convenzioni Laravel

File e Classi

Tipo	Convenzione	Esempio
Model	Singolare, PascalCase	User.php, ProjectStatus.php
Controller	Singolare, PascalCase, suffisso Controller	UserController.php
Service	Singolare, PascalCase, suffisso Service	PaymentService.php
Trait	Singolare, PascalCase, suffisso descrittivo	Notifiable.php, HasApiTokens.php
Interface	Singolare, PascalCase, può avere prefisso I	RepositoryInterface.php
Migration	Data_descrizione_snake_case	2024_01_20_create_users_table.php
Seeder	Singolare, PascalCase, suffisso Seeder	UserSeeder.php
Factory	Singolare, PascalCase, suffisso Factory	UserFactory.php
Test	PascalCase, suffisso Test	UserServiceTest.php

Database

Tipo	Convenzione	Esempio
Tabelle	Plurale, snake_case	users, project_statuses
Pivot Tables	Singolare, snake_case, in ordine alfabetico	user_project
Colonne	snake_case	first_name, created_at
Foreign Keys	singolare_table_id	user_id, project_id
Primary Keys	id	id

Metodi e Variabili

Tipo	Convenzione	Esempio
Metodi	camelCase	getUser(), sendEmail()
Variabili	camelCase	$firstName, $emailAddress
Costanti	SCREAMING_SNAKE_CASE	USER_STATUS_ACTIVE
Proprietà	camelCase	public $firstName

Enums

Tipo	Convenzione	Esempio
Enum	PascalCase, singolare, suffisso Enum	UserStatusEnum, PaymentTypeEnum
Enum Keys	SCREAMING_SNAKE_CASE	PENDING, IN_PROGRESS, COMPLETED
Enum Values	snake_case	pending, in_progress, completed
Enum Methods	camelCase	toString(), fromValue()

tip

Gli enum dovrebbero essere utilizzati per rappresentare un insieme fisso di valori possibili. Ogni valore dovrebbe avere un nome descrittivo e significativo.

Route e View

Tipo	Convenzione	Esempio
Route	kebab-case	users/show-archived
Route Names	dot.notation	admin.users.index
Views	kebab-case	show-user.blade.php
Config	snake_case	app.timezone

Relazioni Eloquent

Tipo	Convenzione	Esempio
hasOne/belongsTo	singolare, camelCase	public function user()
hasMany/belongsToMany	plurale, camelCase	public function comments()
scope	scope + descrizione, camelCase	public function scopeActive()

tip

È importante notare che queste convenzioni non sono solo una questione di stile, ma spesso sono necessarie per il corretto funzionamento delle funzionalità di Laravel come l'auto-discovery dei modelli, il binding delle rotte e il service container.

Commenti

Ogni service dovrà essere ben commentato (gli LLM aiutano molto). Nel resto delle classi è opzionale e gradito ma non paticolarmente necessario dato che per Models, Controllers, Listeners ecc, la business logic non viene implementata direttamente.

Tools

Per garantire la consistenza del codice e prevenire errori, ogni sviluppatore deve avere installato e configurato i seguenti strumenti di formattazione:

• PINT per PHP (VSCode/Cursor, PHPStorm)
• ESLint per linting JavaScript/TypeScript (VSCode/Cursor, PHPStorm)
• Prettier per formattazione JavaScript/TypeScript (VSCode/Cursor, PHPStorm)

Questi strumenti permettono di:

• Mantenere uno stile di codice uniforme attraverso la formattazione automatica
• Identificare problemi potenziali durante lo sviluppo
• Prevenire commit con errori di formattazione o violazioni delle regole
• Migliorare la leggibilità e manutenibilità del codice

Si raccomanda di configurare questi strumenti per la formattazione automatica al salvataggio del file.

Logs

Logging in Canali Specifici

Per garantire una gestione efficace dei log e facilitare il debugging, è fondamentale utilizzare canali di logging specifici organizzati per modulo e argomento. Questo approccio è particolarmente importante per i servizi che si interfacciano con server di terze parti.

Organizzazione dei Canali

Per ogni modulo, sono presenti 3 canali standard per la gestione dei log:

• general: Per errori e informazioni generiche del modulo
• validation: Per errori di validazione
• db: Per errori relativi al database

info

All'interno di ogni modulo, utilizzare canali specifici per argomenti/servizi particolari come per esempio "pay/stripe" oppure "mc/bonus"

Esempio di Configurazione

// config/logging.php
'channels' => [
    'pay/general' => [
        'driver' => 'daily',
        'path' => storage_path('logs/PayModule/general.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => env('LOG_DAILY_DAYS', 14),
        'replace_placeholders' => true,
    ],
    'pay/validation' => [
        'driver' => 'daily',
        'path' => storage_path('logs/PayModule/validation.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => env('LOG_DAILY_DAYS', 14),
        'replace_placeholders' => true,
    ],
    'pay/db' => [
        'driver' => 'daily',
        'path' => storage_path('logs/PayModule/db.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => env('LOG_DAILY_DAYS', 14),
        'replace_placeholders' => true,
    ],
    'pay/stripe' => [
        'driver' => 'daily',
        'path' => storage_path('logs/PayModule/stripe.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => env('LOG_DAILY_DAYS', 14),
        'replace_placeholders' => true,
    ],
]

Best Practices per Servizi di Terze Parti

1. Log delle Richieste: Registrare sempre richieste in uscita con payload e headers
2. Log delle Risposte: Tracciare risposte, codici di stato e tempi di risposta
3. Log degli Errori: Dettagliare errori di rete, timeout e fallimenti

Environment files

È fondamentale mantenere sincronizzati i file di ambiente .env.example e .env.testing con il file .env principale. Ogni volta che viene aggiunta o modificata una variabile d'ambiente nel .env, è necessario aggiornare anche gli altri file di configurazione. Questo garantisce che i nuovi sviluppatori abbiano un template completo e aggiornato per configurare l'ambiente locale e che i test automatizzati utilizzino le variabili d'ambiente corrette. La mancata sincronizzazione di questi file può portare a errori difficili da diagnosticare e a configurazioni incomplete degli ambienti di sviluppo.

warning

Attualmente la sincronizzazione dei file .env deve essere effettuata manualmente. In futuro verrà implementato uno script di pre-commit per automatizzare questo processo e garantire la coerenza tra i file di configurazione.