前言典型的开场是这样的项目里引入了两个第三方库各自定义了一个Logger类运行起来直接PHP Fatal error: Cannot declare class Logger, because the name is already in use。更难受的是另一种不报错但new Logger()拿到的根本不是你以为的那个对象等到调用writeJson()时才炸出Call to undefined method Logger::writeJson()排查半天才发现实例来自另一个库。根源在于 PHP 的全局符号表global symbol table。在同一个请求周期内类、接口、Trait、枚举共享同一张顶层名字表函数名和常量名各有一张独立的表但同样会冲突。两个库各自写class Logger {}PHP 手上没有任何依据去区分它们只能让后声明的那个失败。这里必须先纠正一个事实错误命名空间namespace不是 PHP 8.4 引入的特性它是 PHP 5.3.0 就有的。之所以会跟 8.4 扯上关系是因为 PHP 8.4 新增了属性钩子Property Hooks和非对称可见性asymmetric visibility等成员语法这些新写法放进带命名空间的类里时use该怎么写、类型名怎么解析是 8.4 项目里真实会踩的坑。本文按事实讲命名空间自 5.3 起可用8.4 只在成员语法层面做了扩充。全文分五部分冲突是怎么发生的、名字解析的四条规则、use的四种导入形式与别名、PSR-4 自动加载如何让命名空间真正落地以及 PHP 8.0 至 8.4 的新成员语法放进命名空间时的注意点。所有示例都可以直接存成.php运行。一、类名冲突到底是怎么发生的PHP 在编译一个请求时会把所有被加载的类注册进一张全局表表的主键就是类名不带命名空间时两个同名类就是同一个键。?php // lib_a.php class Logger { public function write(string $m): void { echo A:{$m}\n; } }?php // lib_b.php class Logger { public function write(string $m): void { echo B:{$m}\n; } }只要这两个文件被同一个请求加载第二个就会触发致命错误。注意它是编译期错误try/catch拦不住整个请求直接终止。函数和常量的表现略有不同但同样麻烦符号类型重复声明时的表现能否被 try/catch 捕获类 / 接口 / Trait / 枚举Fatal error: Cannot declare class X不能脚本直接结束函数Fatal error: Cannot redeclare log()不能常量const/defineWarning: Constant VERSION already defined能但值已被先定义的那个占住类方法不冲突只取决于类是否同名不涉及命名空间的做法就是给每个符号加前缀把Logger变成VendorA\Logger和VendorB\Logger两把不同的键冲突自然消失。二、名字解析的四条规则PHP 解析一个类名时严格按下面四条走没有例外完全不限定名unqualified name形如Logger补上当前命名空间 →App\Logger。类名没有全局回退找不到就是Error: Class App\Logger not found。限定名qualified name形如Sub\Logger当前命名空间 该名字 →App\Sub\Logger。完全限定名fully qualified nameFQN形如\VendorA\Logger直接用不补任何前缀。namespace\Logger显式表示当前命名空间结果等同规则 1但读代码的人不用去数文件顶部的namespace声明。写法在namespace App;中的解析结果说明LoggerApp\Logger无全局回退找不到即 ErrorSub\LoggerApp\Sub\Logger相对当前命名空间\VendorA\LoggerVendorA\Logger绝对名字namespace\LoggerApp\Logger显式相对字符串VendorA\LoggerVendorA\Logger字符串形式永远按完全限定名解释Logger::classApp\Logger编译期解析受use影响最容易被忽略的是最后两行字符串形式的类名不受当前命名空间影响也不会被use影响而Logger::class是编译期解析的会被use影响。写class_exists()、容器绑定、工厂方法时这个差异直接决定代码对不对。三、use 的四种导入形式和别名use是编译期的别名声明它不会加载任何文件而且只影响完全不限定名。?php declare(strict_types1); namespace App; use VendorA\Logger; // 类 use VendorA\Logger as ALogger; // 类别名 use function VendorA\log; // 函数 use const VendorA\VERSION; // 常量 use VendorA\{Logger, Client}; // 组导入PHP 7.0 use VendorA\{Logger as ALogger2}; // 组导入 别名如果两条use导入了同名的东西use VendorA\Logger; use VendorB\Logger; // Fatal error: Cannot use VendorB\Logger as Logger // because the name is already in use这是编译期错误脚本连一行都跑不到。所以必须用as起别名区分。另外use语句只能写在文件顶层的命名空间作用域里。把它写进类体、函数体或者enum的花括号里都是语法错误。四、PSR-4 自动加载让命名空间落地命名空间只是名字要让new真的能把类造出来还得有文件被加载。现代 PHP 用自动加载autoloading事实标准是 PSR-4命名空间前缀 ↔ 目录前缀类名中剩余部分按\映射成子目录。?php declare(strict_types1); spl_autoload_register(function (string $class): void { $prefix App\\; $baseDir __DIR__ . /src/; $len strlen($prefix); if (strncmp($prefix, $class, $len) ! 0) { return; // 前缀不匹配交给下一个注册的加载器 } $relative substr($class, $len); $file $baseDir . str_replace(\\, /, $relative) . .php; if (is_file($file)) { require $file; } });这样App\Service\Mailer就对应src/Service/Mailer.php。生产项目一般直接用 Composer 生成的vendor/autoload.php规则完全一样只是前缀和目录的配对写在composer.json的autoload.psr-4里改了之后记得执行一次composer dump-autoload。补充PHP 8.0 ~ 8.4 的新成员语法放进命名空间命名空间本身没变变的是类里面的成员。几处值得留意的构造函数属性提升constructor property promotionPHP 8.0提升出来的参数类型名一样遵循第二节的解析规则推荐在文件顶部use完整类名。枚举enumPHP 8.1枚举也是类也占用全局符号表同样需要命名空间use不能写进enum体内。只读属性readonly propertyPHP 8.1与只读类readonly classPHP 8.2只是修饰符不影响名字解析。#[\Override]PHP 8.3属性里的名字同样是类名按完全限定名解析写法上#[\Override]与文件顶部use Override;后写#[Override]在语义上等价但同一个文件里两种写法混用会让读代码的人困惑选一种即可。属性钩子Property HooksPHP 8.4与非对称可见性asymmetric visibilityPHP 8.4两者只是成员修饰语法与命名空间解析无关但钩子体里出现的类名同样遵守第二节的规则。下面这段把 PHP 8.4 的属性钩子和命名空间放在一个文件里可以直接运行?php declare(strict_types1); namespace App\Support { class Slugger { public static function make(string $s): string { return trim(strtolower(preg_replace(/[^a-z0-9]/i, -, $s)), -); } } } namespace App\Model { use App\Support\Slugger; class Article { public private(set) string $slug ; // 8.4 非对称可见性 public string $title { // 8.4 属性钩子 get $this-title; set (string $value) { $this-title $value; $this-slug Slugger::make($value); } } } } namespace App { use App\Model\Article; $a new Article(); $a-title Hello Namespace 8.4; echo $a-slug, PHP_EOL; // hello-namespace-8-4 // $a-slug x; // Error非对称可见性外部只读 }实战完整可运行示例下面这个文件在单个文件里模拟两个库各自定义Logger用命名空间把冲突消解掉同时演示别名、函数/常量导入和字符串类名的坑。?php declare(strict_types1); namespace VendorA { const VERSION 1.0; function log(string $msg): void { echo [A] {$msg}\n; } class Logger { public function write(string $msg): void { echo VendorA\\Logger: {$msg}\n; } } } namespace VendorB { const VERSION 2.0; function log(string $msg): void { echo [B] {$msg}\n; } class Logger { public function write(string $msg): void { echo VendorB\\Logger: {$msg}\n; } } } namespace App { use VendorA\Logger as ALogger; use VendorB\Logger as BLogger; use function VendorA\log as aLog; use const VendorB\VERSION as B_VERSION; $a new ALogger(); $b new BLogger(); $a-write(hello); $b-write(world); aLog(function import works); echo B_VERSION . B_VERSION . PHP_EOL; // 完全限定名不依赖任何 use (new \VendorA\Logger())-write(fqn works); echo __NAMESPACE__ . __NAMESPACE__ . PHP_EOL; // 字符串类名总按完全限定名解释不吃 use var_dump(class_exists(Logger)); // bool(false)会去找全局 Logger var_dump(class_exists(VendorA\Logger)); // bool(true) var_dump(class_exists(ALogger::class)); // bool(true)::class 是编译期解析 }输出VendorA\Logger: hello VendorB\Logger: world [A] function import works B_VERSION 2.0 VendorA\Logger: fqn works __NAMESPACE__ App bool(false) bool(true) bool(true)常见坑点❌ 以为use会加载文件use App\Service\Mailer;只是编译期别名Mailer.php不会被 include后面new Mailer()照样Class not found。✅加载交给spl_autoload_register()或 Composeruse只管名字。❌ 用字符串写类名在namespace App;里写class_exists(Logger)或$c Logger; new $c;PHP 去找的是全局Logger找不到。✅用Logger::class编译期解析、受use影响或写全App\Logger。❌ 双引号里写命名空间App\Table里的\T会被当成制表符类名活生生变成App TAB able。✅单引号书写或统一用::class单引号里只有\\和\是转义。❌ 两条use同名不加别名use VendorA\Logger; use VendorB\Logger;编译期直接 Fatal error。✅至少给其中一个as别名例如use VendorB\Logger as BLogger;。❌ 以为类名会像函数那样回退到全局在命名空间里调strlen()能回退到全局于是有人以为new Exception()也能自动回退。✅函数和常量有全局回退类没有跨命名空间引用类必须写全名或use。❌ 把declare(strict_types1);写到namespace之后declare必须是文件的第一条语句写在命名空间块里是语法错误。✅顺序固定为?php→declare(...)→namespace ...。❌ 只use了类忘了函数和常量use VendorA\Logger;之后直接调VendorA\log()实际会回退到全局报Call to undefined function log()。✅分别use function VendorA\log;和use const VendorA\VERSION;且常量必须走use const回退只对已定义的常量有效未定义常量在 PHP 8.0 起直接抛Error。❌ 以为一个文件只能有一个namespace于是每个类拆一个文件明明只是几行的小工具类也拆。✅一个文件可以有多个namespace块要么全用花括号、要么全不用不能混测试和示例里很实用。总结要点结论命名空间的引入版本PHP 5.3.0不是 8.48.4 相关的部分属性钩子、非对称可见性只是成员语法与名字解析无关类名解析无全局回退函数、常量有全局回退use的作用编译期别名不加载文件只影响完全不限定名字符串类名永远按完全限定名解释要解析请用::class落地方式PSR-4 spl_autoload_register()/ Composer命名空间本身不复杂四条解析规则加上一张符号表就讲完了真正让人改半天代码的是字符串类名不吃use和类没有全局回退这两条。写新代码时养成两个习惯就能避开绝大多数坑类型名一律走use需要拿类名字符串时一律写Foo::class。