Introduzione a PHP: organizzare un progetto con Composer e autoloading

Introduzione

Quando si inizia a scrivere codice PHP, è comune mettere tutte le istruzioni in un unico file. Questo approccio può funzionare per piccoli esperimenti, ma diventa rapidamente difficile da mantenere quando l’applicazione cresce. Le classi vengono distribuite in cartelle diverse, i file devono essere inclusi manualmente e il rischio di errori aumenta.

In questo tutorial vedremo come usare Composer, il gestore delle dipendenze di PHP, per organizzare un piccolo progetto e caricare automaticamente le classi. L’autoloading permette a PHP di trovare una classe quando viene utilizzata, senza dover scrivere molti comandi require o include.

Realizzeremo una semplice applicazione per gestire prodotti. La classe Product sarà inserita nella cartella src, mentre il file principale public/index.php la utilizzerà grazie all’autoloading PSR-4.

Per seguire l’esempio sono necessari:

PHP 8.1 o una versione successiva;
Composer installato nel sistema;
un terminale e un editor di codice.

Codice completo

Creiamo questa struttura di progetto:

catalogo-prodotti/
├── composer.json
├── src/
│   └── Product.php
└── public/
    └── index.php

Il file composer.json descrive il progetto e configura l’autoloading PSR-4:

{
    "name": "esempio/catalogo-prodotti",
    "description": "Un semplice catalogo di prodotti in PHP",
    "type": "project",
    "require": {
        "php": "^8.1"
    },
    "autoload": {
        "psr-4": {
            "App": "src/"
        }
    }
}

Ora creiamo la classe Product nella cartella src:

<?php

declare(strict_types=1);

namespace App;

final class Product
{
    public function __construct(
        private string $name,
        private float $price
    ) {
        if ($price < 0) {
            throw new InvalidArgumentException(
                ´Il prezzo non può essere negativo.´
            );
        }
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function getPrice(): float
    {
        return $this->price;
    }

    public function formattedPrice(): string
    {
        return number_format(
            $this->price,
            2,
            ´,´,
            ´.´
        ) . ´ €´;
    }
}

Il file pubblico public/index.php carica l’autoloader generato da Composer:

<?php

declare(strict_types=1);

require_once __DIR__ . ´/../vendor/autoload.php´;

use AppProduct;

$products = [
    new Product(´Tastiera meccanica´, 79.90),
    new Product(´Mouse ergonomico´, 34.50),
    new Product(´Monitor 24 pollici´, 159.99),
];
?>
<!DOCTYPE html>
<html lang="it">
<head>
    <meta charset="UTF-8">
    <title>Catalogo prodotti</title>
</head>
<body>
    <h1>Catalogo prodotti</h1>

    <ul>
        <?php foreach ($products as $product): ?>
            <li>
                <strong>
                    <?= htmlspecialchars(
                        $product->getName(),
                        ENT_QUOTES,
                        ´UTF-8´
                    ) ?>
                </strong>
                -
                <?= $product->formattedPrice() ?>
            </li>
        <?php endforeach; ?>
    </ul>
</body>
</html>

Per installare le dipendenze e generare l’autoloader, esegui dalla cartella principale:

composer install
composer dump-autoload

Per avviare il server integrato di PHP:

php -S localhost:8000 -t public

Apri quindi il browser all’indirizzo http://localhost:8000.

Spiegazione

Il ruolo di Composer

Composer permette di dichiarare le dipendenze di un progetto in modo riproducibile. Il file composer.json contiene le informazioni principali dell’applicazione e specifica quali versioni di PHP o quali librerie sono necessarie.

Quando viene eseguito composer install, Composer legge questo file, installa ciò che serve e genera la cartella vendor. Al suo interno viene creato anche vendor/autoload.php, il file che permette di caricare automaticamente classi e pacchetti.

Namespace e PSR-4

La classe appartiene al namespace App:

namespace App;

Nel file composer.json abbiamo associato il namespace App alla cartella src/. Di conseguenza, la classe AppProduct deve trovarsi nel file src/Product.php.

Questa convenzione segue lo standard PSR-4. Il nome completo della classe determina il percorso del file. Per esempio, una classe chiamata AppServicesPriceCalculator dovrebbe trovarsi in:

src/Services/PriceCalculator.php

Nel file principale utilizziamo:

use AppProduct;

In questo modo possiamo scrivere semplicemente Product invece di AppProduct.

Tipi dichiarati e proprietà private

La direttiva declare(strict_types=1) rende più rigorosi i controlli sui tipi scalari. La classe dichiara che il nome è una stringa e il prezzo è un numero decimale:

private string $name;
private float $price;

Le proprietà sono private, quindi non possono essere modificate direttamente dall’esterno. L’oggetto espone metodi pubblici come getName() e formattedPrice(). Questo principio, chiamato incapsulamento, aiuta a proteggere lo stato interno della classe.

Best practice

Usa Composer anche nei progetti piccoli: imparare subito una struttura standard evita di dover riorganizzare il codice in seguito.
Separa il codice pubblico: usa una cartella come public per i file accessibili dal browser e mantieni il resto fuori dalla directory pubblica.
Definisci i namespace: riducono i conflitti tra classi con lo stesso nome e rendono il progetto più ordinato.
Dichiara i tipi: parametri, proprietà e valori restituiti tipizzati rendono il codice più prevedibile.
Non modificare manualmente la cartella vendor: viene generata da Composer e può essere ricreata in qualsiasi momento.
Proteggi l’output HTML: quando visualizzi dati variabili nella pagina, usa htmlspecialchars() per ridurre il rischio di attacchi XSS.
Versiona composer.json e composer.lock: il primo descrive le dipendenze, mentre il secondo blocca le versioni installate.
Usa nomi coerenti: una classe dovrebbe avere un nome descrittivo e il file dovrebbe avere lo stesso nome della classe.

In un progetto reale, la classe Product potrebbe essere affiancata da repository, servizi e controller. Grazie all’autoloading, ogni componente può essere collocato nel proprio file senza dover gestire manualmente decine di inclusioni.

Riepilogo

Composer è uno strumento fondamentale per sviluppare applicazioni PHP moderne. Oltre a installare librerie esterne, genera un autoloader che permette di usare le classi in modo automatico.

In questo esempio abbiamo configurato il namespace App, collegandolo alla cartella src tramite PSR-4. Abbiamo poi creato una classe tipizzata, validato il prezzo nel costruttore e utilizzato l’oggetto da un file pubblico senza scrivere un require diretto per la classe.

La sequenza essenziale da ricordare è:

creare il file composer.json;
configurare l’autoloading PSR-4;
organizzare le classi nelle cartelle corrette;
eseguire composer install o composer dump-autoload;
includere una sola volta vendor/autoload.php.

Approfondisci con risorse ufficiali

Add as preferred source on Google