PHP 命名空間完整教學：定義、使用、導入與解析規則

為什麼需要命名空間

1. 解決命名衝突：專案類別、函式、常數與 PHP 內建或第三方庫重名。
2. 簡化長類別名：透過別名縮短如 `Very\Long\Namespace\ClassName` → `ShortName`。
3. 程式碼組織：將相關類別、函式、常數邏輯分組。

定義命名空間

基本語法

<?php
namespace MyProject;

class MyClass { /* ... */ }
function myFunction() { /* ... */ }
const MY_CONST = 1;

**規則**：`namespace` 必須是檔案**第一行**程式碼（前面只能有 `declare`）。

子命名空間（層級結構）

namespace MyProject\Helper\Http;

class Request { /* ... */ }

同一檔案多個命名空間（不推薦）

<?php
namespace A { class Foo {} }
namespace B { class Bar {} }

僅適用於合併多個舊腳本，現代專案**一檔一命名空間**。

使用命名空間元素

三種引用方式

匯入與別名

<?php
namespace App;

use My\Full\Classname as Another;   // 類別別名
use My\Full\NSname;                 // 等同 use My\Full\NSname as NSname
use \ArrayObject;                   // 匯入全域類別

// PHP 7.0+ 群組導入
use My\Full\{ClassA, ClassB, ClassC as C};
use function My\Full\{funcA, funcB};
use const My\Full\{CONST_A, CONST_B};

**注意**：PHP **不支援**導入函式或常數到別名（僅支援類別/介面/Traits）。

名稱解析規則

1. **完全限定名稱** 編譯期解析：`new \A\B` → 類別 `A\B`。
2. **非限定/限定名稱** 依匯入規則編譯期轉換：`use A\B\C as C` → `C\D\e()` 轉為 `A\B\C\D\e()`。
3. **命名空間內部** 未轉換的限定名稱自動加上目前命名空間前綴：`A\B` 內呼叫 `C\D\e()` → `A\B\C\D\e()`。
4. **非限定類別名** 依匯入規則編譯期轉換：`use A\B\C as C` → `new C()` → `new A\B\C()`。
5. **函式/常數** 非限定名稱**執行期**解析：先找目前命名空間，再找全域空間。

實務範例

<?php
namespace A;
use B\D, C\E as F;

// 函式呼叫
foo();        // 1. A\foo()  2. 全域 foo()
\foo();       // 全域 foo()
my\foo();     // A\my\foo()
F();          // 1. A\F()  2. 全域 F()

// 類別實例化
new B();      // A\B -> autoload A\B
new D();      // B\D (匯入規則)
new F();      // C\E (匯入規則)
new \B();     // 全域 B
new \D();     // 全域 D

// 靜態方法
B\foo();      // A\B\foo()
B::foo();     // A\B::foo() -> autoload A\B
D::foo();     // B\D::foo() (匯入)
\B\foo();     // 全域 B\foo()
\B::foo();    // 全域 B::foo()

自動載入 (PSR-4)

現代專案配合 Composer 自動載入，目錄結構對應命名空間：

src/
├── App/
│   ├── Controller/
│   │   └── UserController.php  // namespace App\Controller;
│   └── Model/
│       └── User.php            // namespace App\Model;

// composer.json
"autoload": {
    "psr-4": {
        "App\\": "src/App/"
    }
}

最佳實務建議

• **一檔一類別、一檔一命名空間**。
• **目錄結構對應命名空間層級**（PSR-4）。
• **善用 `use` 導入與別名**，頂部宣告依賴關係清晰可見。
• **避免全域空間類別**，所有業務邏輯置於專案命名空間下。
• **基底類別、介面置於獨立命名空間**（如 `App\Core`、`App\Contracts`）。