PHP Namespace: namespace, use and Aliases

A PHP namespace puts classes, functions and constants under a prefix so their names cannot collide with someone else's. You declare it with namespace App\Models; as the first statement of a file, and other files refer to the class as \App\Models\User, or import it with use App\Models\User; and write just 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";

Inside the namespace, User means App\Models\User. User::class gives the full name as a string without creating anything, which is handy for logging and for autoloaders.

Two namespaces in one file

A real project puts one namespace in each file. For a self-contained demo, one file may hold several namespaces when each is wrapped in braces. Code that belongs to no namespace goes 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";
}

Two classes called Order live side by side because their full names differ. That is exactly the problem namespaces solve once you install libraries: your Order, a payment library's Order and a PDF library's Order no longer clash.

Import with use, and alias with as

Writing \Shop\Order everywhere is noisy. use at the top of a file (or namespace block) imports a name so you can use the short form. When two imports would end in the same short name, as gives one of them a different name:

<?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 only creates a short name for the rest of the file. It does not load a file or run code, and it works the same whether or not the class exists yet. Grouped imports are also allowed: use Shop\{Order, Invoice};.

use function and use const

Functions and constants in a namespace are imported with use function and 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";
}

Global classes need a backslash

Inside a namespace, an unqualified class name is resolved relative to that namespace, so new DateTime() inside namespace App; looks for App\DateTime. Functions and constants are different: if App\strlen does not exist, PHP falls back to the global strlen. Classes never fall back.

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

The catch (\Error $e) needed a backslash for the same reason: without it PHP would look for App\Error, never match the real error, and the script would stop with an uncaught Error. Fix it either with a leading backslash, as above, or with use DateTime; at the top of the file. The same applies to \Exception, \Throwable and every other built-in class; see try catch for catching them.

Autoloading and PSR-4

In a project, each class lives in its own file, and the file path follows the namespace. PSR-4 is the convention: a namespace prefix maps to a base folder, and the rest of the name becomes the path. An autoloader registered with spl_autoload_register() then loads a class file the first time the class is used. This block writes two class files to disk and autoloads them:

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

Each class file is loaded once, at the moment the class is first needed. In real projects you do not write this function yourself: Composer generates it from a few lines in composer.json:

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

After composer dump-autoload, a single require __DIR__ . '/vendor/autoload.php'; at the start of your entry script loads every App\... class on demand.

Namespace rules that cause errors

• namespace must be the first statement in the file. Only declare(strict_types=1); and comments may come before it.
• use imports are per file. Importing a class in index.php does not make the short name work inside an included file; each file needs its own use lines.
• use belongs at the top level of the file or namespace block. Inside a class body, use means something else: it pulls in a trait.
• Strings are never resolved: $class = 'User'; new $class(); looks for the global User. Store the full name, ideally with User::class.

The last one deserves a quick check:

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