PSR-1 è lo standard promosso da PHP-FIG (PHP Framework Interop Group) che vuole definire le regole per la scrittura di codice PHP così da facilitare la lettura e la comprensione del codice da parte della community degli sviluppatori.

Prima di procedere con la lettura della lezione sullo standard PSR1 consiglio di leggere le note in fondo alla pagina. Inoltre, nella sezione “Lezioni“, è possibile trovare altro materiale sugli standard PHPFIG.

PSR-1: in breve

  • I file PHP DEVONO usare solo i tag <?php e <?=,
  • DEVONO usare solo la codifica UTF-8 priva di BOM,
  • DOVREBBERO dichiarare classi, funzioni, costanti, … OPPURE DOVREBBERO eseguire altri tipi di azioni logiche come generare output, modificare parametri di configurazione del php.ini, includere file … ma NON DOVREBBERO fare entrambe le cose.
  • I Namespaces e i Class Names DEVONO seguire lo standard per “autoloading” PSR-4: una sola classe in un solo file, namespace di almeno un livello indicante il vendor-name.
  • I Class Names DEVONO essere dichiarati in StudlyCaps.
  • Le costanti DEVONO essere dischiarate in maiuscolo utilizzando l’underscore come separatore.
  • I nomi dei metodi DEVONO essere dichiarati in camelCase.

PSR-1: files

PHP Tags

Il codice PHP deve essere dichiarato attraverso i tag <?php ?> oppure gli short-echo <?= ?> tags. NON DEVE utilizzare altre varianti di tag dichiarativi (es: <? ?>).

Codifica dei caratteri

Il file PHP DEVE utilizzare solo la codifica UTF-8 ed essere privo di BOM.

Dichiarazioni ed effetti collaterali (side effects)

Un file DOVREBBE dichiarare nuovi “simboli” (classi, funzioni, costanti, …) senza causare altri “effetti collaterali” OPPURE DOVREBBE eseguire una logica con effetti collaterali, MA NON DOVREBBE fare entrambe le cose.

Lo standard spiega che l’espressione “effetti collaterali” (side effects) indica l’esecuzione di una logica non direttamente correlata alla dichiarazione di classi, funzioni, costanti, ecc, ma correlata direttamente all’inclusione del file stesso.

Vengono poi fatti alcuni esempi di “effetti collaterali” a titolo esemplificativo: generazione di output, uso esplicito di require o include, connessione a servizi esterni, modifica di parametri del php.ini, generazione di errori o eccezioni, modifica di variabili statiche o globali, lettura/scrittura di file, …

Ecco un esempio di file non conforme allo standard con la coopresenza di dichiarazioni ed “effetti collaterali”.

<?php
// effetto collaterale: cambio ini setting
ini_set('error_reporting', E_ALL);

// effetto collaterale: carico un file
include "file.php";

// effetto collaterale: genero output
echo "<html>\n";

// dichiarazione una funzione
function foo() {
    // function body
}

Il seguente esempio mostra un file conforme allo standard contenete solo delle dichiarazioni:

<?php
// dichiarazione una funzione
function foo() {
    // function body
}

// la dichiarazione condizionale non è un effetto collaterale.
if (! function_exists('bar')) {
    function bar() {
        // function body
    }
}

PSR-1: namespace e class names

I namespaces ed i class names DEVONO essere conformi ad allo standard per l’autoloading PSR-4.

Ciò significa che ogni classe DEVE essere dichiarata in un file dedicato e DEVE trovarsi in un Namespace di almeno un livello indicante il vendor-name, in pratica l’indicazione dello sviluppatore.

I class names DEVONO essere dichiarati in StudlyCaps.

ll codice scritto da PHP 5.3 in avanti DEVE utilizzare namespaces formali.

<?php
// PHP 5.3 e successivi:
namespace Vendor\Model;

class Foo {
  // Class body
}

Il codice scritto per PHP 5.2 e versioni precedenti DOVREBBE usare la convenzione pseudo-namespacing con prefissi Vendor_ nei nomi delle classi.

<?php
// PHP 5.2.x e versioni precedenti:
class Vendor_Model_Foo {
  // Class body
}

PSR-1: costanti di classe, proprietà e metodi

Il termine “class” si usa qui in senso più ampio per riferirsi a tutte le classi, le interfacce ed i traits.

Costanti

Le costanti di classe DEVONO essere dischiarate in maiuscolo utilizzando l’underscore come separatore. Personalmente applico questa regola a tutte le costanti comprese quelle definite con define().

<?php
namespace Vendor\Model;

class Foo {
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

Proprietà

Lo standard evita intenzionalmente di fornire consigli riguardanti l’uso dei nomi di prorpietà $StudlyCaps, $camelCase, or $under_score property names.

Qualunque sia la convenzione di denominazione utilizzata DOVREBBE essere applicato in modo coerente.

Metodi

I nomi dei metodi DEVONO essere dichiarati in camelCase().

PSR1 nel lavoro di tutti i giorni

Il nuovo framework CoreBox che stiamo sviluppando alla Communication Box adererisce perfettamente allo standard PSR1. Questo facilita notevolmente lo sviluppo poiché ogni componente del team trova sempre una certa familiarità nel leggere il codice scritto dai colleghi.

Note

Quando si legge un documento del PHP-FIG le parole DEVE (MUST), NON DEVE (MUST NOT), RICHIESTO (REQUIRED), POTRÀ (SHALL), NON POTRÀ (SHALL NOT), DOVREBBE (SHOULD), NON DOVREBBE (SHOULD NOT), RACCOMANDATO (RECCOMANDED), PUÒ (MAY) e OPZIONALE (OPTIONAL) vanno interpretati secondo quanto descritto nel documento RFC 2119.

Lo stile StudlyCaps, noto anche come PascalCase, impone che la prima lettera di ogni parola sia in maiuscolo. Una stringa in questo stile deve iniziare sempre con la lettera maiuscola.

Lo stile camelCase, proprio come in un cammello, impone che le gobbe siano solo in mezzo. Una stringa in questo stile deve iniziare sempre con la lettera minuscola.