PHP 命名空间

// 没有命名空间时，两个库都有 User 类会冲突
// require 'library1/User.php'; // class User {}
// require 'library2/User.php'; // class User {} ← 致命错误！
``
命名空间不仅解决了冲突问题，还让代码的组织结构更加清晰。通过命名空间，可以直观地看出一个类属于哪个模块或层次，例如 App\Http\Controllers\UserController 一眼就能看出这是应用的 HTTP 控制器层中的用户控制器。

定义命名空间
命名空间声明必须是文件的第一条语句（注释除外），使用 namespace 关键字，层级之间用反斜杠 \ 分隔。

`php
// 必须是文件第一行（除注释外）
namespace App\Models;

class User {
    public function __construct(public string $name) {}
}
`

`php
namespace App\Controllers;

class UserController {
    public function index(): void {
        echo '用户列表';
    }
}
`

一个文件只应包含一个命名空间声明，这是 PSR-1 规范的要求。虽然 PHP 语法上允许在一个文件中定义多个命名空间，但这种做法会让代码难以维护，应当避免。
使用命名空间
在一个命名空间中使用另一个命名空间的类，有两种方式：使用完全限定名称（带前导反斜杠），或者用 use 语句导入后使用简短名称。

`php
namespace App;

// 方式一：完全限定名称
$user = new \App\Models\User('张三');
// 方式二：use 导入
use App\Models\User;
use App\Controllers\UserController;
$user       = new User('张三');
$controller = new UserController();
`

use 语句放在命名空间声明之后、类定义之前，可以一次导入多个类。在同一文件中频繁使用某个命名空间下的多个类时，可以用 use App\Models\{User, Product, Order} 的组合导入语法，更加简洁。

别名
当两个不同命名空间下有同名类时，可以用 as 关键字为其中一个（或两个）创建别名，避免冲突。别名也可以用来缩短过长的类名。

`php
use App\Models\User as UserModel;
use App\Models\AdminUser as Admin;
use App\Http\Request;

// 解决同名冲突
use Database\Query as DBQuery;
use Illuminate\Database\Query as EloquentQuery;
`

别名只在当前文件有效，不会影响其他文件。use 语句本身不会触发类的加载，只是在当前文件的作用域内创建一个名称映射，实际加载由自动加载器负责。

子命名空间
命名空间可以有多个层级，形成树状结构，通常与目录结构一一对应。这种对应关系是 PSR-4 自动加载规范的基础。
`php
namespace App\Http\Controllers\Api\V1;

class ProductController {
    // ...
}
`

`php
use App\Http\Controllers\Api\V1\ProductController;

$ctrl = new ProductController();
`

命名空间的层级深度没有限制，但实际项目中通常不超过 4-5 层，过深的层级会让代码难以阅读。常见的层级结构是：厂商名\应用名\模块名\子模块名。

命名空间与文件结构
现代 PHP 项目遵循 PSR-4 规范，命名空间与目录结构对应：
`
src/
├── Models/
│   ├── User.php          → namespace App\Models;
│   └── Product.php       → namespace App\Models;
├── Controllers/
│   └── UserController.php → namespace App\Controllers;
└── Services/
    └── MailService.php    → namespace App\Services;
`

PSR-4 规范要求：命名空间前缀对应一个基础目录，命名空间的每个子层级对应该目录下的子目录，类名对应文件名（大小写敏感）。遵循这个规范后，Composer 的自动加载器可以根据类名自动找到对应的文件，无需手动 require。

全局命名空间
在有命名空间的文件中，访问全局类（如 DateTime、Exception）和全局函数（如 json_decode）时，需要加前导反斜杠，或者用 use 导入。

`php
namespace App\Utils;

// 访问全局类/函数需要加反斜杠
$date = new \DateTime();          // 全局 DateTime 类
$arr  = \json_decode($json, true); // 全局函数
$e    = new \Exception('错误');
// 或者 use 导入
use DateTime;
use Exception;
$date = new DateTime();
`

PHP 在解析类名时，会先在当前命名空间查找，找不到才去全局命名空间。但函数和常量的解析规则不同：函数会先在当前命名空间查找，找不到会自动回退到全局命名空间（无需加反斜杠）；类则不会自动回退，必须显式指定。
命名空间函数与常量
命名空间不仅可以包含类，还可以包含函数和常量。使用时同样需要 use function 和 use const 语法导入。

`php
namespace App\Utils;

function formatMoney(float $amount): string {
    return '¥' . number_format($amount, 2);
}
const VERSION = '1.0.0';
`

`php
use function App\Utils\formatMoney;
use const App\Utils\VERSION;

echo formatMoney(9999); // ¥9,999.00
echo VERSION;           // 1.0.0
`

命名空间函数和常量在实际项目中使用较少，更常见的做法是将工具函数封装为静态类方法，或者使用全局辅助函数文件（在 composer.json 的 autoload.files 中注册）。

实际项目结构示例
下面是一个典型的 MVC 项目中命名空间的使用方式，展示了控制器如何引用模型，以及 Composer 自动加载的配置。
`php
// composer.json 中配置 PSR-4 自动加载
// "autoload": { "psr-4": { "App\\": "src/" } }

// src/Models/User.php
namespace App\Models;
class User {
    public static function find(int $id): ?static {
        // 查询数据库...
        return null;
    }
}
// src/Controllers/UserController.php
namespace App\Controllers;
use App\Models\User;
class UserController {
    public function show(int $id): void {
        $user = User::find($id);
        if (!$user) {
            http_response_code(404);
            return;
        }
        echo $user->name;
    }
}