PHP 中的命名空间如何工作？

Question

PHP 中的命名空间如何工作？

Accepted Answer

**命名空间**组织 PHP 代码并防止 classes、functions 和 constants 之间的**命名冲突** — 随着应用程序增长和使用第三方包，这至关重要。它们像 class 名称的目录一样工作，并与 Composer autoloading (PSR-4) 集成。

## 命名空间解决的问题

```text
Without namespaces, two classes named `User` (yours and a library's) would COLLIDE
("cannot redeclare class"). Namespaces give each a unique fully-qualified name.
```

## 声明和使用命名空间

```php
<?php
// declare a namespace at the top of the file (matches the directory, PSR-4)
namespace App\Models;

class User {            // fully-qualified name: App\Models\User
    // ...
}
```

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

use App\Models\User;            // IMPORT a class so you can use its short name
use App\Services\Mailer as MailService;   // import with an ALIAS

class UserController {
    public function index() {
        $user = new User();      // short name works thanks to the `use` import
        // or use the fully-qualified name: new \App\Models\User();
    }
}
```

一个文件声明其 `namespace`，其他文件用短名称 `use`（导入）classes。完全限定名（`\App\Models\User`）在全局范围内是唯一的。

## 命名空间映射到目录 (PSR-4)

```text
Namespace            File path
App\Models\User   →  src/Models/User.php
App\Services\Mailer → src/Services/Mailer.php
→ PSR-4 autoloading: the namespace structure mirrors the folder structure, so
  Composer can find and load each class automatically (no manual require).
```

## 导入 functions、constants 和全局命名空间

```php
use function App\Helpers\format;     // import a function
use const App\Config\VERSION;        // import a constant

\strlen("x");    // a leading \ = the GLOBAL namespace (built-in functions)
```

## 为什么这很重要

命名空间对于组织现代 PHP 代码至关重要，是整个生态系统工作方式的基础。

理解它们很重要，因为它们解决了**命名冲突**的关键问题 — 没有命名空间，你的 classes 会相互冲突，也会与真实应用程序使用的许多第三方包冲突（两个 `User` classes 不能并存），使大型应用程序和包生态系统变得不可能。

命名空间为每个 class 提供唯一的完全限定名，**`use` 导入**让你能够简洁地通过短名称引用 classes。

最重要的是，命名空间与 **Composer 通过 PSR-4 的 autoloading** 集成，其中命名空间结构镜像目录结构，所以 classes 会按需自动加载 — 这是现代 PHP 项目结构和依赖管理的基础。

由于每个现代 PHP 框架、包和应用程序都是用命名空间组织的（而且不理解命名空间就无法使用 Composer 包），知道如何声明命名空间、用 `use` 导入 classes，以及它们如何映射到目录进行 autoloading，是任何现代 PHP 开发的基础日常知识。

命名空间、Composer 和 PSR-4 autoloading 共同定义了当代 PHP 项目的结构。