Scrivere codice pulito in PHP significa ridurre bug, velocizzare manutenzione e rendere i progetti più sostenibili nel tempo. In questa guida vediamo le regole fondamentali: standard PSR-12, formattazione e naming, tipi e strict mode, gestione degli errori, test e i principi SOLID applicati a casi reali, con esempi concreti.
“Codice pulito” in PHP non è un vezzo estetico: è una scelta tecnica che incide su manutenzione, bug, tempi di sviluppo e collaborazione. In pratica, è ciò che ti permette di tornare su un progetto dopo mesi (o di passarlo a un altro sviluppatore) senza doverlo “decifrare” come fosse un messaggio in bottiglia.
In questa guida mettiamo ordine nelle regole fondamentali per scrivere codice pulito in PHP: standard di formattazione e convenzioni, tipi e strict mode, gestione degli errori, organizzazione del progetto, test e principi SOLID applicati. L’obiettivo è uno: scrivere codice più leggibile, più prevedibile e più facile da cambiare.
1) Parti da uno standard: PSR-12 e coerenza prima dello stile
Il primo passo verso un codice pulito è semplice: scegli uno standard e rispettalo sempre. In PHP, lo standard più comune per lo stile di codice è PSR-12 (PHP-FIG), che definisce linee guida su indentazione, spaziatura, dichiarazioni, organizzazione del codice e molto altro. :contentReference[oaicite:0]{index=0}
Lo standard non serve a “vincere discussioni” nel team: serve a ridurre frizione, rendere il codice uniforme e permettere agli strumenti automatici di fare il lavoro sporco (formattazione e controlli).
Regole pratiche (che fanno davvero la differenza)
- Indentazione coerente (tipicamente 4 spazi, niente tab).
- Spaziatura leggibile attorno agli operatori e tra blocchi logici.
- Una riga vuota tra metodi per separare sezioni.
- Visibilità sempre dichiarata (public/private/protected) per proprietà e metodi.
Queste linee guida sono spesso riassunte anche in buone pratiche di formattazione per classi e metodi, come nell’esempio di riferimento che cita PSR-12 come standard ufficiale. :contentReference[oaicite:1]{index=1}
2) Naming: se un nome è vago, il codice è già più difficile
Il clean code inizia dai nomi. Un nome sbagliato “nasconde” il significato e costringe chi legge a ricostruire mentalmente l’intento. In PHP, una convenzione molto usata è:
- Classi in PascalCase (es.
OrderService) - Metodi e variabili in camelCase (es.
calculateTotal())
È una regola semplice, ma soprattutto serve coerenza. Anche qui, le linee guida di base (classi PascalCase, metodi camelCase) sono un punto fermo della formattazione ordinata. :contentReference[oaicite:2]{index=2}
Checklist naming (veloce e utile)
- Preferisci nomi specifici (non
$data, ma$orderData). - I metodi dovrebbero iniziare con un verbo (
create,build,validate). - Evita abbreviazioni criptiche: risparmiano 2 caratteri e costano 20 minuti.
3) Tipi e strict mode: meno ambiguità, meno bug
PHP oggi consente una tipizzazione molto più robusta rispetto al passato. Se vuoi codice pulito, sfrutta:
- type hints per parametri e return
- strict_types quando ha senso
- property types e constructor promotion
<?php
declare(strict_types=1);
final class PriceCalculator
{
public function calculateTotal(float $net, float $vatRate): float
{
return $net * (1 + $vatRate);
}
}
Questo approccio rende l’API della classe più chiara, riduce conversioni implicite e aiuta i tool di analisi statica.
4) Funzioni piccole, responsabilità singole: il principio che paga sempre
Un indicatore immediato di “codice sporco” è una funzione che fa troppe cose: valida, trasforma, salva su DB, invia email e magari scrive log. Quando tutto è dentro lo stesso metodo, ogni modifica diventa rischiosa.
Qui entra in gioco il primo principio SOLID, il Single Responsibility Principle (SRP): una classe dovrebbe avere un solo motivo per cambiare. :contentReference[oaicite:3]{index=3}
Esempio (prima: tutto insieme, difficile da manutenere)
final class OrderController
{
public function checkout(array $payload): void
{
// valida input
// calcola totali
// salva ordine
// invia email
// logga operazione
}
}
Dopo: responsabilità separate (più pulito, testabile)
final class CheckoutService
{
public function __construct(
private OrderValidator $validator,
private OrderRepository $repository,
private Mailer $mailer,
private LoggerInterface $logger
) {}
public function checkout(OrderRequest $request): void
{
$this->validator->validate($request);
$order = Order::fromRequest($request);
$this->repository->save($order);
$this->mailer->sendOrderConfirmation($order);
$this->logger->info('Order created', ['id' => $order->id()]);
}
}
Non è “più lungo”: è più chiaro. E soprattutto è più facile da testare.
5) SOLID in PHP: cosa cambia davvero nella pratica
I principi SOLID sono cinque linee guida di progettazione orientata agli oggetti (OOP) pensate per rendere il codice più manutenibile, estendibile e robusto. :contentReference[oaicite:4]{index=4}
S – Single Responsibility (una responsabilità)
Una classe non dovrebbe diventare un “contenitore di tutto”. Se cresce troppo, spezzala in componenti più piccoli e focalizzati.
O – Open/Closed (aperto a estensioni, chiuso a modifiche)
Quando aggiungi una feature, cerca di estendere senza modificare il comportamento esistente (riduce regressioni). Tipico esempio: strategie, handler, provider.
L – Liskov Substitution (sostituibilità)
Se una sottoclasse rompe le aspettative della classe base, la gerarchia è sbagliata. Se ti viene da “lanciare eccezioni” perché un metodo non ha senso nella sottoclasse, stai segnando un problema di design.
I – Interface Segregation (interfacce piccole)
Meglio più interfacce piccole che una enorme che obbliga le classi a implementare metodi inutili.
D – Dependency Inversion (dipendere da astrazioni)
Le classi di alto livello dovrebbero dipendere da interfacce, non da classi concrete. Questo riduce accoppiamento e migliora la testabilità.
Se vuoi un riepilogo chiaro dei cinque principi e delle loro definizioni, è utile anche una fonte sintetica (con elenco completo e significato di ogni lettera). :contentReference[oaicite:5]{index=5}
6) Evita “magic numbers” e costanti sparse
Un altro classico del codice difficile: numeri e stringhe ripetuti ovunque. Se un valore è significativo, dagli un nome.
final class Invoice
{
private const VAT_STANDARD = 0.22;
public function vatRate(): float
{
return self::VAT_STANDARD;
}
}
È una best practice semplice e molto citata nelle regole di formattazione e organizzazione del codice. :contentReference[oaicite:6]{index=6}
7) Error handling: eccezioni, messaggi chiari, niente silenzi
Codice pulito significa anche errori puliti. Linee guida pratiche:
- Usa eccezioni per errori “eccezionali”, non per il flusso normale.
- Non sopprimere errori con
@. - Scrivi messaggi che aiutino davvero a capire il problema.
throw new DomainException('Order total cannot be negative.');
Se un errore non lascia traccia, diventa un bug “fantasma”: costoso.
8) Commenti: meno, ma migliori
I commenti non devono spiegare “cosa fa il codice” se il codice è già chiaro. Devono spiegare:
- perché una scelta è stata fatta
- un vincolo di business
- un caso limite non ovvio
Anche nelle linee guida di formattazione si insiste su commenti chiari e concisi per logiche complesse. :contentReference[oaicite:7]{index=7}
9) Automatizza lo stile: formatter e linter
La disciplina manuale non scala. In un progetto reale conviene automatizzare:
- PHP-CS-Fixer o PHP_CodeSniffer (con regole PSR-12)
- PHPStan o Psalm per analisi statica
- pre-commit hook o CI per bloccare codice non conforme
Risultato: meno discussioni in review e più tempo su architettura e qualità.
10) Test: il vero moltiplicatore della pulizia
Se il codice non è testabile, spesso non è pulito. Non perché “mancano i test”, ma perché è troppo accoppiato, troppo grande o troppo dipendente dall’ambiente.
Quando applichi principi come SRP e Dependency Inversion, i test unitari diventano più facili. E quando i test sono facili, il refactoring diventa sostenibile.
Conclusione
Scrivere codice pulito in PHP significa adottare standard (come PSR-12), curare naming e formattazione, ridurre ambiguità con i tipi, gestire errori in modo esplicito e progettare con responsabilità chiare. I principi SOLID non sono teoria: sono una bussola pratica per scrivere codice più semplice da mantenere, estendere e testare nel tempo. Se vuoi un obiettivo concreto: rendi il codice leggibile, prevedibile e noioso (nel senso migliore). È così che diventa professionale.
Pubblicato in PHP
Commenta per primo