PHP Namespace: namespace, use und Aliase

Ein PHP-Namespace stellt Klassen, Funktionen und Konstanten unter ein Präfix, damit ihre Namen nicht mit denen anderer kollidieren. Du deklarierst ihn mit namespace App\Models; als erste Anweisung einer Datei, und andere Dateien sprechen die Klasse als \App\Models\User an oder importieren sie mit use App\Models\User; und schreiben nur 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";

Im Namespace bedeutet User dasselbe wie App\Models\User. User::class liefert den vollen Namen als String, ohne etwas zu erzeugen, praktisch für Logging und für Autoloader.

Zwei Namespaces in einer Datei

Ein echtes Projekt legt einen Namespace pro Datei an. Für eine in sich geschlossene Demo darf eine Datei mehrere Namespaces enthalten, wenn jeder in geschweifte Klammern gesetzt ist. Code, der zu keinem Namespace gehört, kommt 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";
}

Zwei Klassen namens Order leben nebeneinander, weil sich ihre vollen Namen unterscheiden. Genau dieses Problem lösen Namespaces, sobald du Bibliotheken installierst: Dein Order, das Order einer Zahlungsbibliothek und das Order einer PDF-Bibliothek kollidieren nicht mehr.

Mit use importieren und mit as einen Alias vergeben

Überall \Shop\Order zu schreiben ist unübersichtlich. use am Anfang einer Datei (oder eines Namespace-Blocks) importiert einen Namen, sodass du die kurze Form verwenden kannst. Wenn zwei Importe auf denselben kurzen Namen enden würden, gibt as einem davon einen anderen Namen:

<?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 erzeugt nur einen kurzen Namen für den Rest der Datei. Es lädt keine Datei und führt keinen Code aus und funktioniert gleich, ob die Klasse schon existiert oder nicht. Gruppierte Importe sind ebenfalls erlaubt: use Shop\{Order, Invoice};.

use function und use const

Funktionen und Konstanten in einem Namespace importierst du mit use function und 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";
}

Globale Klassen brauchen einen Backslash

In einem Namespace wird ein nicht qualifizierter Klassenname relativ zu diesem Namespace aufgelöst, also sucht new DateTime() in namespace App; nach App\DateTime. Bei Funktionen und Konstanten ist es anders: Existiert App\strlen nicht, fällt PHP auf das globale strlen zurück. Klassen fallen nie zurück.

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

catch (\Error $e) brauchte aus demselben Grund einen Backslash: Ohne ihn würde PHP nach App\Error suchen, den echten Fehler nie treffen, und das Skript würde mit einem nicht abgefangenen Error stoppen. Behebe es entweder mit einem führenden Backslash, wie oben, oder mit use DateTime; am Anfang der Datei. Dasselbe gilt für \Exception, \Throwable und jede andere eingebaute Klasse; siehe try catch zum Abfangen.

Autoloading und PSR-4

In einem Projekt lebt jede Klasse in ihrer eigenen Datei, und der Dateipfad folgt dem Namespace. PSR-4 ist die Konvention: Ein Namespace-Präfix wird einem Basisordner zugeordnet, und der Rest des Namens wird zum Pfad. Ein mit spl_autoload_register() registrierter Autoloader lädt dann eine Klassendatei, sobald die Klasse zum ersten Mal verwendet wird. Dieser Block schreibt zwei Klassendateien auf die Festplatte und lädt sie automatisch:

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

Jede Klassendatei wird einmal geladen, in dem Moment, in dem die Klasse zum ersten Mal gebraucht wird. In echten Projekten schreibst du diese Funktion nicht selbst: Composer erzeugt sie aus ein paar Zeilen in composer.json:

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

Nach composer dump-autoload lädt ein einziges require __DIR__ . '/vendor/autoload.php'; am Anfang deines Einstiegsskripts jede App\...-Klasse bei Bedarf.

Namespace-Regeln, die Fehler verursachen

• namespace muss die erste Anweisung der Datei sein. Nur declare(strict_types=1); und Kommentare dürfen davor stehen.
• use-Importe gelten pro Datei. Eine Klasse in index.php zu importieren, lässt den kurzen Namen nicht in einer eingebundenen Datei funktionieren; jede Datei braucht ihre eigenen use-Zeilen.
• use gehört auf die oberste Ebene der Datei oder des Namespace-Blocks. In einem Klassenrumpf bedeutet use etwas anderes: Es bindet einen Trait ein.
• Strings werden nie aufgelöst: $class = 'User'; new $class(); sucht nach dem globalen User. Speichere den vollen Namen, am besten mit User::class.

Die letzte Regel verdient eine kurze Prüfung:

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