命名空间

是什么，为什么存在

命名空间（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 和枚举；函数与常量使用相似但独立的导入表。

以反斜杠开头的 完全限定名称（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。全局代码导入一个原名和一个别名，短名称在当前文件中保持唯一。

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

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

看见函数回退

App\Text 自己声明了 strlen()，所以非限定调用选中它。没有声明本地 count() 时，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();
}

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

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

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，读者更容易追踪。

陷阱

把导入误当成加载

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

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

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

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

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

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

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

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

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

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

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

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

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

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

混淆导入与闭包捕获

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

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

延伸阅读

• PHP 手册：命名空间概览
• PHP 手册：名称解析规则
• PHP 手册：导入与别名
• PHP 手册：回退到全局空间
• PHP-FIG：PSR-4 自动加载规范
• Composer 配置结构：PSR-4