Namespace in PHP: namespace, use e alias

Un namespace PHP mette classi, funzioni e costanti sotto un prefisso così i loro nomi non possono entrare in conflitto con quelli di qualcun altro. Lo dichiari con namespace App\Models; come prima istruzione di un file, e gli altri file si riferiscono alla classe come \App\Models\User, oppure la importano con use App\Models\User; e scrivono solo User.

<?php
namespace App\Models;

class User
{
    public function __construct(public string $name) {}
}

function greet(User $u): string
{
    return "Hello, {$u->name}";
}

$u = new User('Ada');
echo greet($u), "\n";
echo User::class, "\n";
echo __NAMESPACE__, "\n";
echo get_class($u), "\n";

Dentro il namespace, User significa App\Models\User. User::class dà il nome completo come stringa senza creare nulla, comodo per il logging e per gli autoloader.

Due namespace in un file

Un progetto reale mette un namespace in ogni file. Per una demo autonoma, un file può contenerne diversi quando ciascuno è racchiuso tra graffe. Il codice che non appartiene a nessun namespace va in namespace { }:

<?php
namespace Shop {
    class Order
    {
        public function label(): string { return 'shop order'; }
    }
}

namespace Kitchen {
    class Order
    {
        public function label(): string { return 'kitchen ticket'; }
    }
}

namespace {
    // Global code: use the fully qualified names
    $a = new \Shop\Order();
    $b = new \Kitchen\Order();
    echo get_class($a), ': ', $a->label(), "\n";
    echo get_class($b), ': ', $b->label(), "\n";
}

Due classi chiamate Order vivono fianco a fianco perché i loro nomi completi sono diversi. È esattamente il problema che i namespace risolvono quando installi librerie: il tuo Order, l'Order di una libreria di pagamenti e l'Order di una libreria PDF non si scontrano più.

Importare con use e creare alias con as

Scrivere \Shop\Order ovunque è pesante. use in cima a un file (o a un blocco namespace) importa un nome così puoi usare la forma breve. Quando due import finirebbero con lo stesso nome breve, as dà a uno dei due un nome diverso:

<?php
namespace Shop {
    class Order { public string $kind = 'shop'; }
    class Invoice { public string $kind = 'invoice'; }
}

namespace Kitchen {
    class Order { public string $kind = 'kitchen'; }
}

namespace App {
    use Shop\Order;
    use Shop\Invoice;
    use Kitchen\Order as KitchenOrder;

    $orders = [new Order(), new KitchenOrder(), new Invoice()];
    foreach ($orders as $o) {
        echo get_class($o), ' -> ', $o->kind, "\n";
    }
    echo KitchenOrder::class, "\n";
}

use crea solo un nome breve per il resto del file. Non carica un file né esegue codice, e funziona allo stesso modo che la classe esista già o no. Sono consentiti anche gli import raggruppati: use Shop\{Order, Invoice};.

use function e use const

Le funzioni e le costanti di un namespace si importano con use function e use const:

<?php
namespace Utils\Text {
    const ELLIPSIS = '...';

    function shorten(string $s, int $max): string
    {
        return mb_strlen($s) > $max ? mb_substr($s, 0, $max) . ELLIPSIS : $s;
    }
}

namespace App {
    use function Utils\Text\shorten;
    use const Utils\Text\ELLIPSIS;

    echo shorten('Namespaces keep names apart', 10), "\n";
    echo 'Marker: ', ELLIPSIS, "\n";
    echo \Utils\Text\shorten('Fully qualified call works too', 15), "\n";
}

Le classi globali richiedono una barra rovesciata

Dentro un namespace, un nome di classe non qualificato viene risolto rispetto a quel namespace, quindi new DateTime() dentro namespace App; cerca App\DateTime. Funzioni e costanti sono diverse: se App\strlen non esiste, PHP ripiega sullo strlen globale. Le classi non ripiegano mai.

<?php
namespace App;

echo strlen('works'), "\n";        // functions fall back to global
echo PHP_INT_SIZE, "\n";               // so do constants

try {
    $d = new DateTime('2026-03-14');
} catch (\Error $e) {
    echo $e->getMessage(), "\n";
}

$d = new \DateTime('2026-03-14');  // leading backslash: the global class
echo $d->format('D, d M Y'), "\n";

Anche catch (\Error $e) richiedeva una barra rovesciata per lo stesso motivo: senza, PHP cercherebbe App\Error, non corrisponderebbe mai al vero errore, e lo script si fermerebbe con un Error non catturato. Risolvi con una barra rovesciata iniziale, come sopra, oppure con use DateTime; in cima al file. Lo stesso vale per \Exception, \Throwable e ogni altra classe predefinita; vedi try catch per catturarle.

Autoloading e PSR-4

In un progetto, ogni classe vive nel proprio file, e il percorso del file segue il namespace. PSR-4 è la convenzione: un prefisso di namespace corrisponde a una cartella di base, e il resto del nome diventa il percorso. Un autoloader registrato con spl_autoload_register() carica poi il file di una classe la prima volta che la classe viene usata. Questo blocco scrive su disco due file di classe e li carica automaticamente:

<?php
// Create src/Models/User.php and src/Services/Mailer.php
is_dir('src/Models') || mkdir('src/Models', 0777, true);
is_dir('src/Services') || mkdir('src/Services', 0777, true);
file_put_contents('src/Models/User.php', '<?php
namespace App\Models;
class User { public function __construct(public string $email) {} }
');
file_put_contents('src/Services/Mailer.php', '<?php
namespace App\Services;
use App\Models\User;
class Mailer { public function welcome(User $u): string { return "Welcome mail to {$u->email}"; } }
');

// A minimal PSR-4 autoloader: App\ maps to src/
spl_autoload_register(function (string $class) {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class\n";
    require $file;
});

$mailer = new App\Services\Mailer();
echo $mailer->welcome(new App\Models\User('ada@example.com')), "\n";

Ogni file di classe viene caricato una volta, nel momento in cui la classe serve per la prima volta. Nei progetti reali non scrivi tu questa funzione: Composer la genera da poche righe in composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Dopo composer dump-autoload, un solo require __DIR__ . '/vendor/autoload.php'; all'inizio dello script di ingresso carica su richiesta ogni classe App\....

Regole dei namespace che causano errori

• namespace deve essere la prima istruzione del file. Possono precederlo solo declare(strict_types=1); e i commenti.
• Gli import con use valgono per file. Importare una classe in index.php non fa funzionare il nome breve dentro un file incluso; ogni file ha bisogno delle proprie righe use.
• use va al livello principale del file o del blocco namespace. Dentro il corpo di una classe, use significa un'altra cosa: include un trait.
• Le stringhe non vengono mai risolte: $class = 'User'; new $class(); cerca lo User globale. Salva il nome completo, meglio se con User::class.

L'ultima merita una verifica veloce:

<?php
namespace App\Models {
    class User {}
}

namespace App {
    use App\Models\User;

    $short = 'User';
    var_dump(class_exists($short));         // looks for global User
    var_dump(class_exists(User::class));    // App\Models\User

    $class = User::class;
    echo get_class(new $class()), "\n";
}