PHP 命名空间：namespace 与 use 语句

命名空间是 PHP 5.3 引入的一个重要特性，它解决了类名和函数名冲突的问题。当你的项目规模变大，或者你需要整合多个第三方库时，命名空间能让代码保持整洁有序。本文将手把手教你掌握命名空间的核心用法。

为什么需要命名空间

在没有命名空间的时代，如果你定义了一个 User 类，后来引入的第三方库也定义了 User 类，PHP 就会抛出 "Class 'User' already exists" 的致命错误。命名空间相当于给类、函数和常量创建了一个"文件夹"，不同的"文件夹"里可以存放同名的"文件"。

想象一个文件系统：如果没有目录，所有文件都平铺在根目录下，必然会频繁出现重名问题。命名空间正是这个道理，它让代码组织更加清晰，避免命名冲突。

定义命名空间

基本语法

使用 namespace 关键字在文件顶部定义命名空间。注意：声明命名空间的语句必须是 PHP 文件的第一行代码，前面不能有任何输出（包括空格）。

<?php
namespace App\Models;

class User
{
    // 这个类位于 App\Models 命名空间下
}

上面的代码定义了一个位于 App\Models 命名空间下的 User 类。完整的类名（Fully Qualified Class Name）是 App\Models\User，这类似于文件的路径 App/Models/User.php。

多级命名空间

命名空间可以使用反斜杠 \ 分隔多级层级，推荐使用 Composer 自动加载规范中的 PSR-4 标准来组织你的命名空间。

<?php
namespace App\Controllers\User;

class ProfileController
{
    // 这个类位于 App\Controllers\User 命名空间下
}

同一文件多个命名空间（不推荐）

PHP 允许在同一个文件中定义多个命名空间，但不推荐这样做。保持一个文件一个类或一个文件一个命名空间是更好的实践。

<?php
namespace App\Models;

class User
{
}

namespace App\Services;

class UserService
{
}

使用命名空间

完全限定名称

直接使用完整的命名空间路径来访问类，这是最原始但最繁琐的方式。

<?php
// 直接使用完整的命名空间
$user = new \App\Models\User();
```

开头的反斜杠 `\` 表示"从根命名空间开始"，即绝对路径。

### use 语句导入命名空间

使用 `use` 语句可以导入命名空间或类，之后只需使用简短的类名即可。这是最常用的方式。

```php
<?php
namespace App\Controllers;

use App\Models\User;

class UserController
{
    public function show($id)
    {
        // 直接使用 User，无需完整的命名空间路径
        $user = new User();
        return $user->find($id);
    }
}
```

### 导入函数和常量

`use` 语句默认用于导入类，但 PHP 7 之后也支持导入函数和常量。

```php
<?php
use function App\Helpers\formatDate;
use const App\Constants\STATUS_ACTIVE;

echo STATUS_ACTIVE;         // 直接使用常量
formatDate($timestamp);     // 直接使用函数

使用别名

当两个不同的命名空间下存在同名的类时，可以为其中一个或全部指定别名来区分。

<?php
use App\Models\User as AppUser;
use OtherLib\Models\User as OtherUser;

$user1 = new AppUser();     // 来自 App\Models
$user2 = new OtherUser();   // 来自 OtherLib\Models

别名也可以用于命名空间本身，这在处理嵌套命名空间时非常有用。

实战示例

组织项目结构

假设你的项目结构如下，每个目录对应一个命名空间：

src/
├── Controllers/
│   └── HomeController.php
├── Models/
│   ├── User.php
│   └── Product.php
└── Services/
    └── PaymentService.php

HomeController.php 的完整实现：

<?php
namespace App\Controllers;

use App\Models\User;
use App\Services\PaymentService;

class HomeController
{
    private $paymentService;

    public function __construct()
    {
        $this->paymentService = new PaymentService();
    }

    public function index()
    {
        $user = new User();
        $users = $user->all();
        
        return [
            'users' => $users,
            'service_status' => $this->paymentService->getStatus()
        ];
    }
}
```

### 解决命名冲突

当你需要同时使用两个不同库中的同名类时，命名空间和别名是唯一的解决方案。

```php
<?php
use Illuminate\Database\Eloquent\Model as EloquentModel;
use Symfony\Component\HttpFoundation\File\File as SymfonyFile;

// 使用 Laravel 的 Eloquent 模型
class Article extends EloquentModel
{
    // 
}

// 使用 Symfony 的文件类
$file = new SymfonyFile('/path/to/file');

全局命名空间

如果在文件中没有声明 namespace，那么类、函数和常量就位于全局命名空间中。全局命名空间中的类在使用时不需要任何前缀。

<?php
// 没有 namespace 声明，位于全局命名空间

class ArrayObject
{
    // 与 SPL 的 ArrayObject 同名，但不冲突
}

调用全局命名空间中的类时，可以使用前缀 \ 来明确表示"从全局命名空间开始"：

<?php
namespace App\Models;

$array = new \ArrayObject();    // 明确使用全局命名空间中的 ArrayObject
$array2 = new ArrayObject();    // 等价于上面的写法，因为当前命名空间下没有 ArrayObject

命名空间与自动加载

命名空间必须配合自动加载机制才能发挥作用。Composer 是 PHP 事实上的标准自动加载工具，它根据 PSR-4 标准自动加载符合命名空间约定的类。

在你的 composer.json 中配置自动加载规则：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "Database\\": "lib/database/"
        }
    }
}

配置完成后，运行 composer dump-autoload 更新自动加载映射，之后就可以直接在代码中使用命名空间了。

常见问题与注意事项

1. 命名空间的分隔符

命名空间的分隔符是反斜杠 \ 而不是正斜杠 /。在代码中输入时，注意不要与文件路径混淆。

2. 类名的解析顺序

当 PHP 解析一个类名（如 User）时，它会按照以下顺序查找：

• 当前命名空间下是否有 User
• 是否通过 use 语句导入了 User
• 最后才会认为是全局命名空间下的 User

<?php
namespace App\Models;

use OtherLib\User;   // 这里的 use 是明确的

class User           // 声明在当前命名空间，优先级最高
{
    // 本地的 User 类
}

$local = new User();         // 解析为 App\Models\User
$other = new \OtherLib\User();   // 明确使用全局命名空间下的 OtherLib\User

3. 命名空间与 include/require

include 和 require 语句与命名空间无关，它们仍然按照文件路径来加载文件。确保你的自动加载配置正确，或者手动加载时使用正确的文件路径。

4. 命名空间命名规范

遵循 PSR-4 标准，命名空间应该与文件目录结构对应。例如：

• App\Controllers 对应 src/Controllers 目录
• 命名空间名称使用 PascalCase
• 避免使用过长的命名空间层级

总结要点

命名空间是组织大规模 PHP 代码的基础设施。掌握 namespace 和 use 的组合使用，能够让你的代码结构清晰、模块分明，同时彻底解决命名冲突问题。从今天起，让你的每个 PHP 类都"住进"合适的命名空间里。