Namespace PHP : namespace, use et alias

Un namespace PHP place des classes, des fonctions et des constantes sous un préfixe pour que leurs noms ne puissent pas entrer en conflit avec ceux de quelqu'un d'autre. Vous le déclarez avec namespace App\Models; comme première instruction d'un fichier, et les autres fichiers désignent la classe par \App\Models\User, ou l'importent avec use App\Models\User; et écrivent simplement 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";

Dans le namespace, User signifie App\Models\User. User::class donne le nom complet sous forme de chaîne sans rien créer, ce qui est pratique pour les logs et les autoloaders.

Deux namespaces dans un fichier

Un vrai projet met un namespace par fichier. Pour une démo autonome, un fichier peut contenir plusieurs namespaces si chacun est entouré d'accolades. Le code qui n'appartient à aucun namespace va dans 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";
}

Deux classes nommées Order cohabitent car leurs noms complets diffèrent. C'est exactement le problème que résolvent les namespaces une fois que vous installez des bibliothèques : votre Order, l'Order d'une bibliothèque de paiement et l'Order d'une bibliothèque PDF n'entrent plus en conflit.

Importer avec use, et créer un alias avec as

Écrire \Shop\Order partout est lourd. use en haut d'un fichier (ou d'un bloc de namespace) importe un nom pour que vous puissiez utiliser la forme courte. Quand deux imports aboutiraient au même nom court, as donne un autre nom à l'un d'eux :

<?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 ne crée qu'un nom court pour le reste du fichier. Il ne charge aucun fichier, n'exécute aucun code, et fonctionne de la même façon que la classe existe déjà ou non. Les imports groupés sont aussi permis : use Shop\{Order, Invoice};.

use function et use const

Les fonctions et constantes d'un namespace s'importent avec use function et 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";
}

Les classes globales demandent une barre oblique inverse

Dans un namespace, un nom de classe non qualifié est résolu par rapport à ce namespace, donc new DateTime() dans namespace App; cherche App\DateTime. Les fonctions et les constantes sont différentes : si App\strlen n'existe pas, PHP se rabat sur le strlen global. Les classes ne se rabattent jamais.

<?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";

Le catch (\Error $e) avait besoin d'une barre oblique inverse pour la même raison : sans elle, PHP chercherait App\Error, ne correspondrait jamais à la vraie erreur, et le script s'arrêterait sur une Error non interceptée. Corrigez-le avec une barre oblique inverse initiale, comme ci-dessus, ou avec use DateTime; en haut du fichier. C'est pareil pour \Exception, \Throwable et toutes les autres classes natives ; voir try catch pour les intercepter.

Autoloading et PSR-4

Dans un projet, chaque classe vit dans son propre fichier, et le chemin du fichier suit le namespace. PSR-4 est la convention : un préfixe de namespace correspond à un dossier de base, et le reste du nom devient le chemin. Un autoloader enregistré avec spl_autoload_register() charge alors le fichier d'une classe la première fois que la classe est utilisée. Ce bloc écrit deux fichiers de classes sur le disque et les charge automatiquement :

<?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";

Chaque fichier de classe est chargé une fois, au moment où la classe est nécessaire pour la première fois. Dans les vrais projets, vous n'écrivez pas cette fonction vous-même : Composer la génère à partir de quelques lignes dans composer.json :

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

Après composer dump-autoload, un seul require __DIR__ . '/vendor/autoload.php'; au début de votre script d'entrée charge chaque classe App\... à la demande.

Les règles de namespace qui provoquent des erreurs

• namespace doit être la première instruction du fichier. Seuls declare(strict_types=1); et des commentaires peuvent le précéder.
• Les imports use valent par fichier. Importer une classe dans index.php ne fait pas fonctionner le nom court dans un fichier inclus ; chaque fichier a besoin de ses propres lignes use.
• use se place au niveau principal du fichier ou du bloc de namespace. Dans le corps d'une classe, use signifie autre chose : il importe un trait.
• Les chaînes ne sont jamais résolues : $class = 'User'; new $class(); cherche le User global. Stockez le nom complet, idéalement avec User::class.

La dernière mérite une vérification rapide :

<?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";
}