# 命名空间

Source: https://codewiki.com/zh/php/namespaces/

> - **what**: 命名空间（namespace）为类、接口、trait、枚举、函数和常量提供分层名称，使不同库可以安全地使用相同短名称。
> - **trap**: `use` 只在当前文件编译名称，并不会加载文件；动态字符串也不会套用导入规则。函数和常量还有类式名称没有的全局回退规则。
> - **fix**: 在文件顶部声明命名空间和导入，动态创建对象时传入 `SomeType::class`，并让 Composer 的 PSR-4 映射与名称、路径及大小写严格一致。

## 是什么，为什么存在

命名空间（namespace）是声明名称的一部分，不是一个运行时容器。`App\Billing\Invoice` 与 `Vendor\Archive\Invoice` 的短名称都叫 `Invoice`，但它们是两个不同的类。项目因此可以组合自有代码和第三方包，而不必给每个类型添加人为前缀。

命名空间可以包含类、接口、trait、枚举、函数和常量。它不隔离变量，也不会建立文件作用域。一个文件中的普通变量仍遵循 PHP 原有的变量作用域规则；命名空间只改变受支持声明及其引用的名称解析方式。

现代 PHP 项目几乎都会在源码中遇到命名空间。框架组件、Composer 包、测试类和领域代码都依靠完整名称区分所有权。即使你只写一个小入口文件，也会在导入 `DateTimeImmutable`、异常类型或库类时使用相同规则。

命名空间解决的是名称冲突和名称组织问题。自动加载（autoloading）解决的是 PHP 在需要某个类式名称时怎样找到并载入定义文件。两者常由 PSR-4 连在一起，但不是同一机制：正确的 `use` 语句无法修复错误的自动加载映射，正确的映射也无法修复错误的类名。

## 工作原理

### 声明与作用范围

非大括号语法用 `namespace App\Billing;` 声明从当前位置到文件结束或下一个命名空间声明之间的命名空间。大括号语法用 `namespace App\Billing { ... }` 明确包住代码。一个文件不能混用两种语法；日常项目通常让每个文件只有一个命名空间，测试夹具或演示代码才常把多个命名空间放在一起。

命名空间声明必须是文件中的第一条语句，但 `declare` 可以放在它之前。起始 `<?php`、空白和注释不算语句；输出、变量赋值与 `require` 都不能抢在声明前面。含有命名空间的文件如果还需要全局代码，必须使用大括号形式的 `namespace { ... }` 块。

命名空间名称以反斜杠分隔层级。名称本身并不要求对应目录，但自动加载标准可以额外建立这种对应关系。源码里应使用稳定的组织边界，例如 `App\Billing`，不要把每一层文件夹都机械地变成业务层级。

### 四种名称写法

PHP 在编译文件时解析静态写出的类式名称。这里的类式名称包括类、接口、trait 和枚举；函数与常量使用相似但独立的导入表。

| 写法 | 示例 | 解析方式 |
| --- | --- | --- |
| 非限定名称 | `Invoice` | 先查对应导入别名；类式名称否则落到当前命名空间 |
| 限定名称 | `Model\Invoice` | 若首段是导入别名则替换它，否则附加到当前命名空间 |
| 完全限定名称 | `\Vendor\Billing\Invoice` | 从全局根开始，不使用当前命名空间 |
| `namespace` 相对名称 | `namespace\Invoice` | 明确附加到当前命名空间 |

以反斜杠开头的完全限定名称（fully qualified name）最明确，但到处重复长名称会遮住业务代码。通常在文件顶部导入一次，然后在正文使用短名称。诊断信息、配置和动态创建对象时，则常需要不带开头反斜杠的完整名称字符串。

### 导入表与别名

`use Vendor\Billing\Invoice;` 为类式名称建立当前文件内的别名 `Invoice`。`use Vendor\Billing\Invoice as VendorInvoice;` 则建立显式的命名空间别名（namespace alias）。别名适合解决两个导入拥有相同短名称的冲突，也能为一个命名空间前缀命名，例如 `use Vendor\Billing as Billing;`。

函数和常量不会借用类式名称的导入表。它们分别使用 `use function Vendor\Text\slugify;` 与 `use const Vendor\Config\VERSION;`。分组导入可以共享前缀，但 `function` 和 `const` 关键字仍要写清楚，因此混合分组过长时往往不如几条普通导入易读。

导入在编译期生效，范围仅限当前文件。被包含的文件不会继承调用方的导入，调用方也不会得到被包含文件的导入。把 `use` 放在命名空间声明之后、其他声明之前，可以让这项文件级约定保持清楚。

### 函数与常量的全局回退

未导入的非限定类式名称只会解析到当前命名空间，不会自动尝试全局类。`new DateTimeImmutable()` 在 `App\Billing` 中指向 `App\Billing\DateTimeImmutable`；要使用内建类，应导入它或写 `new \DateTimeImmutable()`。

非限定函数和常量有所不同。PHP 先尝试当前命名空间中的同名函数或常量，找不到时再回退到全局名称。因此 `strlen()` 可能被当前命名空间的函数遮蔽，而 `\strlen()` 始终明确调用全局函数。对行为敏感的内建函数使用开头反斜杠，可以让调用目标不受后来新增的同名函数影响。

限定函数名、限定常量名和完全限定名称不会执行这种回退。导入也会直接确定目标。审查代码时应区分“当前文件导入了什么”和“运行时找不到非限定函数后回退到了什么”，这两个步骤发生在不同阶段。

### 静态名称与动态字符串

`Invoice::class` 会按照当前文件的导入规则生成完整类名字符串，而且不会仅因为取得这个字符串就加载类。这个表达式适合依赖注入配置、工厂映射和序列化元数据，因为重命名工具也更容易识别它。

动态字符串不会重新经过导入解析。`new $class`、`class_exists($class)` 和回调数组中的字符串都按字符串包含的名称工作；值为 `'Invoice'` 时，它指的是全局短名称，不会变成已导入的 `App\Models\Invoice`。让调用方传 `Invoice::class`，或者在可信映射中保存这些类常量，能避免手工拼接名称。

### 被包含文件保留自己的名称上下文

`include` 或 `require` 的目标文件会按自己的源码编译命名空间声明与导入。调用方位于 `App\Web`，不会让一个没有命名空间声明的被包含文件自动加入 `App\Web`。该文件声明的类仍在全局空间中。

被包含文件可以访问包含位置的变量作用域，但这个变量规则不会改变声明名称。把变量作用域与命名空间当成同一边界，会产生一类很难从 `use` 列表看出的偶然依赖。

重复包含一个声明类或函数的文件，仍可能因为重复声明而失败；命名空间不会把第二次加载变成独立副本。确定只需载入一次时使用 `require_once`，但应用类通常应交给自动加载器按需载入。

自由函数不能由 PSR-4 逐个找到。函数库可以由入口明确载入，或通过 Composer 的 `autoload.files` 载入；无论选择哪种方式，其命名空间声明和函数导入仍按文件独立解析。

## 示例

以下三个示例均由本地 PHP 8.3.33 CLI 执行，输出按实际结果记录。它们依次展示同名类、全局回退和动态类名。

### 用别名区分同名类

两个包都可以声明 `Receipt`。全局代码导入一个原名和一个别名，短名称在当前文件中保持唯一。

<!-- quick -->

```php
// file: receipt_aliases.php
<?php

declare(strict_types=1);

namespace Commerce\Sales {
    final class Receipt
    {
        public function label(): string
        {
            return 'sales receipt';
        }
    }
}

namespace Commerce\Returns {
    final class Receipt
    {
        public function label(): string
        {
            return 'return receipt';
        }
    }
}

namespace {
    use Commerce\Returns\Receipt as ReturnReceipt;
    use Commerce\Sales\Receipt;

    $issued = new Receipt();
    $returned = new ReturnReceipt();

    printf("%s: %s\n", $issued::class, $issued->label());
    printf("%s: %s\n", $returned::class, $returned->label());
}
```

```text
Commerce\Sales\Receipt: sales receipt
Commerce\Returns\Receipt: return receipt
```

<!-- /quick -->

`Receipt` 和 `ReturnReceipt` 只是在最后一个命名空间块中的本地拼写。对象仍属于声明时的完整类名，别名不会创建新类，也不会改变反射、日志或 `$object::class` 返回的名称。

大括号语法让这个单文件示例可以声明两个命名空间并执行全局代码。实际 PSR-4 项目通常会把两个类放进各自文件，并由入口文件载入 Composer 自动加载器。

### 看见函数回退

`App\Text` 自己声明了 `strlen()`，所以非限定调用选中它。没有声明本地 `count()` 时，PHP 才回退到全局函数；开头反斜杠则跳过本地候选。

```php
// file: function_fallback.php
<?php

declare(strict_types=1);

namespace App\Text {
    function strlen(string $value): int
    {
        return \strlen($value) * 10;
    }

    const MODE = 'namespaced';

    function report(): void
    {
        printf("local strlen: %d\n", strlen('php'));
        printf("global strlen: %d\n", \strlen('php'));
        printf("global count: %d\n", count(['a', 'b', 'c']));
        printf("mode: %s\n", MODE);
    }
}

namespace {
    \App\Text\report();
}
```

```text
local strlen: 30
global strlen: 3
global count: 3
mode: namespaced
```

本地 `strlen()` 内部必须写 `\strlen()`；否则它会递归调用自己。`count()` 没有前缀仍能工作，只是因为当前命名空间没有 `App\Text\count()`。如果依赖全局目标是契约的一部分，显式写出它会更稳妥。

常量 `MODE` 也属于 `App\Text`。若函数内既找不到该常量，也找不到全局同名常量，PHP 会产生未定义常量错误，而不是把名称悄悄当作字符串。

### 为动态创建传递完整类名

导入会影响静态的 `Invoice::class`，却不会改写普通字符串 `'Invoice'`。工厂接收已经解析好的完整类名，因此无需猜测调用方的命名空间上下文。

```php
// file: dynamic_class_names.php
<?php

declare(strict_types=1);

namespace App\Models {
    final class Invoice {}
}

namespace App\Factories {
    use App\Models\Invoice;

    final class Factory
    {
        public static function make(string $class): object
        {
            return new $class();
        }

        public static function localName(): string
        {
            return namespace\Factory::class;
        }
    }

    function candidateNames(): array
    {
        return ['Invoice', Invoice::class, \App\Models\Invoice::class];
    }
}

namespace {
    use App\Factories\Factory;
    use function App\Factories\candidateNames;

    foreach (candidateNames() as $candidate) {
        printf("%s => %s\n", $candidate, class_exists($candidate) ? 'found' : 'missing');
    }

    echo Factory::make(\App\Models\Invoice::class)::class, "\n";
    echo Factory::localName(), "\n";
}
```

```text
Invoice => missing
App\Models\Invoice => found
App\Models\Invoice => found
App\Models\Invoice
App\Factories\Factory
```

数组中的后两个值相同：导入后的 `Invoice::class` 与源码写出的完全限定名称都生成 `App\Models\Invoice`。开头反斜杠是源码名称的根标记，不会保留在得到的类名字符串中。

`namespace\Factory::class` 明确引用当前命名空间中的 `Factory`。它在移动整个命名空间的测试夹具中偶尔有用；公开配置通常直接使用导入后的 `Factory::class`，读者更容易追踪。

## 陷阱

### 把导入误当成加载

> **陷阱:** `use Vendor\Package\Client;` 不会执行 `require`，也不保证 `Client` 已定义。它只告诉编译器当前文件中的短名称应解析为什么。

首次使用类式名称时，PHP 可以把解析后的完整名称交给已注册的自动加载器。如果 `vendor/autoload.php` 没有载入、Composer 映射过期，或文件路径不匹配，修饰 `use` 语句仍然会得到 `Class ... not found`。

**修复方法：** 在应用入口载入自动加载器，修改 Composer 自动加载配置后运行 `composer dump-autoload`，并用 `class_exists(ExpectedType::class)` 或真实构造路径验证解析后的名称。先记录自动加载器收到的完整名称，再检查映射。

### 在两个导入中占用同一个短名称

> **陷阱:** 同一导入表不能让 `Vendor\One\Logger` 与 `Vendor\Two\Logger` 都使用别名 `Logger`。第二条导入会在编译时产生名称冲突。

删除其中一条导入并在正文混用完全限定名称，虽然能运行，却会让冲突政策散落在调用点。把两个类型都缩写成难懂的首字母也会把问题转成可读性缺陷。

**修复方法：** 保留领域中最自然的一个短名称，并为另一个选择表达来源或角色的别名，例如 `VendorLogger` 或 `AuditLogger`。别名只在当前文件生效，因此每个文件都要独立作出清楚选择。

### 假设动态字符串会使用导入

> **陷阱:** 生成代码常把 `$class = 'Invoice'; new $class();` 放在已经导入 `App\Models\Invoice` 的文件中。字符串不会因此变成完整类名。

手工拼接 `__NAMESPACE__ . '\\' . $suffix` 只适合所有目标确实位于当前命名空间的封闭协议。若 `$suffix` 来自请求参数，还会把外部输入变成类型选择机制，并可能触发意外类的自动加载与构造副作用。

**修复方法：** 对封闭集合使用从外部键到 `Invoice::class` 等类常量的显式允许列表。构造后再验证共享接口，并在构造前拒绝未知键；不要用 `eval`，也不要把用户输入直接当作类名。

### 忘记类式名称没有全局回退

> **陷阱:** 在 `App\Jobs` 中写 `new DateTimeImmutable()` 会解析为 `App\Jobs\DateTimeImmutable`。函数能回退到全局空间，并不表示类也能。

这种错误常在把全局脚本移入命名空间后出现。代码中的 `strlen()` 继续工作，内建类却突然报告找不到，于是问题容易被误诊为扩展或 Composer 故障。

**修复方法：** 导入所用全局类，或在少量调用点写完整名称 `\DateTimeImmutable`。迁移文件时分别盘点类式名称、函数与常量，不要用一类名称的行为推断另一类。

### 让 PSR-4 的大小写或层级漂移

> **陷阱:** 映射 `Acme\` 到 `src/` 后，`Acme\Billing\InvoiceWriter` 应落在 `src/Billing/InvoiceWriter.php`，并保持目录、文件与类名的大小写一致。

大小写宽松的开发文件系统可能暂时掩盖 `billing` 与 `Billing` 的差别，部署到大小写敏感的系统后才失败。另一个常见漂移是文件路径写成 `Services`，声明却使用 `Service`，导致自动加载器查找另一条路径。

**修复方法：** 让移动文件的提交同时更新命名空间与引用，并在大小写敏感的 CI 环境运行真实入口或测试。对预期类执行 Composer 的自动加载验证，不要只对单个文件运行 `php -l`。

### 混淆导入与闭包捕获

> **陷阱:** 文件级 `use App\Models\Invoice;` 导入类名，而 `function () use ($invoice) { ... }` 把变量复制或按引用带入闭包。两种语法同名，但作用完全不同。

生成代码有时会把类导入写进方法，或者试图用文件级 `use` 导入变量。两者都会失败，因为命名空间导入只能位于顶层，闭包的 `use (...)` 则只能跟在匿名函数参数列表之后。

**修复方法：** 审查时把它们分别称为 `namespace import` 与 `closure capture`。类名放在命名空间声明后的导入区，运行时变量放在闭包捕获列表中，并为按引用捕获单独检查生命周期与可变性。

<!-- deep -->

## 名称解析的编译期边界

PHP 会在编译文件时处理命名空间声明、导入和静态类式引用。`use App\Models\Invoice as Bill;` 建立别名后，`Bill::class`、`new Bill()` 与类型声明 `Bill $invoice` 都指向同一完整名称。别名不是运行时表中的第二个类，也不是 `class_alias()`；后者会建立可由运行时查找的另一个类名，语义明显更强。

导入表按符号种类分开。一个文件可以同时导入类 `Vendor\Clock`、函数 `Vendor\Clock()` 和常量 `Vendor\Clock`，三者的短名称相同却互不覆盖。这样的代码合法但难读，除非库接口迫使你这么做，否则应选择能说明种类和角色的名称。

`::class` 的结果是字符串，并不触发自动加载。随后把该字符串传给 `new`、`class_exists()` 默认启用的自动加载路径，或需要该类型的反射操作时，才可能调用自动加载器。这一阶段边界解释了为什么容器配置可以安全地收集尚未加载的类名，也解释了为什么只打印 `Type::class` 不能证明映射正确。

`__NAMESPACE__` 同样产生当前命名空间的字符串。它适合诊断或少量元编程，但字符串拼接不会获得静态分析和重命名工具对 `::class` 的同等支持。若目标集合已知，显式类常量映射更容易审查。

### 命名空间不是访问控制边界

命名空间不会赋予同一命名空间内的代码特殊访问权限。`public`、`protected` 与 `private` 仍由类和继承关系决定，而不是由名称前缀决定。PHP 也没有“包内可见”这种命名空间级修饰符。

任何代码都可以通过完整名称引用可访问的公开声明，即使它没有写 `use`。导入只改变本地拼写，不会授予权限，也不会隐藏类型。不要把难以猜测的命名空间名称当作安全措施。

命名空间也不会安装或版本化一个包。Composer 的包依赖、自动加载配置和发布边界负责这些工作；两个包仍可能错误地声明同一个完整类名，并在加载时冲突。

若架构要求模块只能通过公开接口相互调用，应由目录所有权、Composer 包边界、静态分析规则和测试共同执行。命名空间可以表达这项设计，但自身不会阻止跨边界引用。

## PSR-4 与 Composer 的连接处

PSR-4定义从完整类式名称到文件路径的自动加载约定。若前缀 `Acme\` 映射到 `src/`，自动加载器会去掉前缀，把余下命名空间分隔符换成目录分隔符，并给终止类名添加 `.php`。例如 `Acme\Billing\InvoiceWriter` 对应 `src/Billing/InvoiceWriter.php`。

Composer 把这项映射写在 `composer.json` 的 `autoload.psr-4` 中。测试专用名称应放在根包的 `autoload-dev.psr-4`，避免把测试类暴露给使用该包的项目。配置改变后运行 `composer dump-autoload`，入口则加载一次 `vendor/autoload.php`。

```json
{
  "autoload": {
    "psr-4": {
      "Acme\\": "src/"
    },
    "files": ["src/functions.php"]
  },
  "autoload-dev": {
    "psr-4": {
      "Acme\\Tests\\": "tests/"
    }
  }
}
```

PSR-4 处理类、接口、trait 和枚举等类式声明，不会按需自动加载自由函数或常量。Composer 的 `autoload.files` 可以在自动加载器初始化时包含一个函数文件，但它的加载时机与逐类 PSR-4 查找不同。函数很多时，也可以把它们放进静态工具类，不过是否这样建模应由 API 形状决定，而不是为了迁就加载器。

一条前缀可以映射到多个基础目录，Composer 会按配置顺序查找。重叠前缀也可以存在，更具体的前缀应表达更窄的所有权。不要依赖碰巧先找到的重复类；同一个完整类名拥有两个定义时，部署结果会受安装内容和加载顺序影响。

`use` 与 PSR-4 的连接点只有解析后的完整名称。编译器先把 `InvoiceWriter` 解析成 `Acme\Billing\InvoiceWriter`，自动加载器再尝试找到文件。排障时按这个顺序记录两个事实：PHP 请求的准确类名，以及该名称按前缀映射得到的准确路径。

<!-- /deep -->

[检查点: php/namespaces](https://codewiki.com/zh/php/namespaces/#checkpoint)

## 延伸阅读

- [PHP 手册：命名空间概览](https://www.php.net/manual/en/language.namespaces.php)
- [PHP 手册：名称解析规则](https://www.php.net/manual/en/language.namespaces.rules.php)
- [PHP 手册：导入与别名](https://www.php.net/manual/en/language.namespaces.importing.php)
- [PHP 手册：回退到全局空间](https://www.php.net/manual/en/language.namespaces.fallback.php)
- [PHP-FIG：PSR-4 自动加载规范](https://www.php-fig.org/psr/psr-4/)
- [Composer 配置结构：PSR-4](https://getcomposer.org/doc/04-schema.md#psr-4)