PHP命名空间是解决类名冲突、实现自动加载和模块化协作的必需机制；必须位于文件顶部（仅declare可前置），用\分隔层级，全局元素需加\前缀，use用于导入别名，PSR-4依赖\映射目录。
PHP 命名空间不是“可选的组织方式”，而是解决类名冲突、实现自动加载和模块化协作的必需机制；不加命名空间的代码在 Composer 项目或现代框架中基本无法被正确引入。
命名空间声明必须放在文件最顶部（除 declare 外）
PHP 解析器对 namespace 的位置极其敏感：它必须是文件中第一个语句，前面只能有 declare 指令或空白/注释。任何输出（包括 BOM、空格、echo）、require 或函数定义都会导致致命错误。
常见错误现象：Fatal error: Namespace declaration statement has to be the very first statement in the script
- 用编辑器检查文件开头是否有 UTF-8 BOM（尤其 Windows 记事本保存的文件）
- 确保
namespace前没有require、include或任何执行语句 - 如果用了
declare(strict_types=1);，它必须在namespace之前，且中间不能有空行
子命名空间用反斜杠分隔，不要用点或下划线
PHP 命名空间层级靠 \ 分隔，与目录结构逻辑对应但无语法绑定；用 . 或 _ 会变成单层非法名称，导致类找不到或解析失败。
立即学习“PHP免费学习笔记（深入）”；
正确写法：namespace App\Controllers\Admin;
错误写法：namespace App.Controllers.Admin; 或 namespace App_Controllers_Admin;
- Composer 自动加载规则（如 PSR-4）默认将
\映射为目录分隔符，所以App\Controllers\User对应src/Controllers/User.php - 命名空间末尾不加
\（即namespace App\;合法，namespace App\;多余的反斜杠会报错） - 避免全大写命名空间（如
namespace API\V1;），虽然语法允许，但与 PSR 规范和主流工具链习惯冲突
use 导入别名时注意类名冲突和相对引用
use 不是“引入文件”，而是为长命名空间创建当前作用域内的短名；未加 use 的类名会被视为当前命名空间下的相对路径，极易误用。
典型问题：Class 'App\Controllers\User' not found，实际是因为写了 new User() 却没 use App\Models\User;，PHP 尝试实例化 App\Controllers\User。
- 用
use时建议显式写出完整命名空间，避免歧义：use App\Models\User as UserModel; - 同名类需强制使用别名，例如同时用
Illuminate\Support\Str和App\Utils\Str，必须至少一个加as -
use function和use const在 PHP 5.6+ 支持，用于导入函数/常量，语法独立于类导入
全局类和函数要加反斜杠前缀
在有命名空间的文件里，直接写 strlen() 或 Exception 会被解析成当前命名空间下的 Current\Namespace\strlen 或 Current\Namespace\Exception，而非 PHP 内置的全局版本。
错误现象：Class 'App\Controllers\Exception' not found，或调用自定义的 json_encode 而非内置函数。
- 所有全局类、函数、常量，在命名空间内使用时必须加前导
\，例如：new \Exception()、\json_encode($data)、\DATE_ISO8601 - 不推荐用
use Exception;简化——这会让代码失去“明确区分全局与自定义”的可读性，也容易掩盖命名空间污染 - 第三方库若未声明命名空间（如纯函数库），其函数默认进入全局空间，调用时仍需加
\
命名空间本身不提升性能，但它是 Composer 自动加载、IDE 符号跳转、静态分析（如 PHPStan）工作的前提；漏掉一个 \ 或错位一个 use，往往表现为“类存在却报找不到”，排查时优先确认命名空间拼写、文件路径映射和加载器配置是否完全一致。
