PHP 命名空间：namespace、use 和别名

PHP 命名空间把类、函数和常量放在一个前缀之下，这样它们的名字就不会和别人的冲突。在文件的第一条语句写 namespace App\Models; 来声明它，其他文件可以用 \App\Models\User 引用这个类，或者用 use App\Models\User; 导入后直接写 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";

在命名空间内部，User 指的是 App\Models\User。User::class 以字符串形式给出完整名称，而不会创建任何东西，这在记录日志和编写自动加载器时很方便。

一个文件中的两个命名空间

实际项目中每个文件放一个命名空间。不过为了做一个独立的演示，如果每个命名空间都用花括号包起来，一个文件也可以包含多个命名空间。不属于任何命名空间的代码放在 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";
}

两个都叫 Order 的类可以并存，因为它们的完整名称不同。安装第三方库之后，命名空间解决的正是这个问题：你的 Order、支付库的 Order 和 PDF 库的 Order 不会再冲突。

用 use 导入，用 as 起别名

到处都写 \Shop\Order 太啰嗦了。在文件（或命名空间块）顶部用 use 导入一个名称，就可以使用简短的形式。当两个导入的短名称相同时，可以用 as 给其中一个换个名字：

<?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 只是为文件的其余部分创建一个短名称。它不会加载文件，也不会运行代码，无论这个类是否已经存在，效果都一样。也可以分组导入：use Shop\{Order, Invoice};。

use function 和 use const

命名空间中的函数和常量用 use function 和 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";
}

全局类需要加反斜杠

在命名空间内部，不带限定的类名会相对于该命名空间解析，所以在 namespace App; 中写 new DateTime() 会去找 App\DateTime。函数和常量则不同：如果 App\strlen 不存在，PHP 会回退到全局的 strlen。类永远不会回退。

<?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) 需要反斜杠也是同样的原因：没有它，PHP 会去找 App\Error，永远匹配不上真正的错误，脚本会因为未捕获的 Error 而停止。修复方法有两种：像上面那样在开头加反斜杠，或者在文件顶部写 use DateTime;。\Exception、\Throwable 以及其他所有内置类也是如此；关于如何捕获它们，请参阅 try catch。

自动加载与 PSR-4

在项目中，每个类都放在自己的文件里，文件路径与命名空间相对应。PSR-4 就是这样的约定：命名空间前缀对应一个基础文件夹，名称的其余部分就成为路径。然后，用 spl_autoload_register() 注册的自动加载器会在类第一次被使用时加载它的文件。这段代码会把两个类文件写入磁盘，并自动加载它们：

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

每个类文件只在第一次需要这个类时加载一次。在实际项目中，你不需要自己编写这个函数：Composer 会根据 composer.json 中的几行配置生成它：

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

运行 composer dump-autoload 之后，只要在入口脚本开头写一行 require __DIR__ . '/vendor/autoload.php';，就会按需加载每个 App\... 类。

会导致错误的命名空间规则

• namespace 必须是文件中的第一条语句。只有 declare(strict_types=1); 和注释可以写在它前面。
• use 导入只对单个文件有效。在 index.php 中导入一个类，并不能让被引入的文件也使用这个短名称；每个文件都需要自己的 use 语句。
• use 应该写在文件或命名空间块的顶层。在类的内部，use 的含义完全不同：它用来引入一个 trait。
• 字符串永远不会被解析：$class = 'User'; new $class(); 会去找全局的 User。请保存完整名称，最好使用 User::class。

最后一条值得快速验证一下：

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