PHP 命名空間宣告的三大核心注意事項詳解

前言

PHP 5.3 引入命名空間機制，有效解決類別、函式、常數命名衝突問題。然而開發者在初次使用時，常因語法細節導致致命錯誤。本文整理三大核心規則，並附上錯誤與正確範例，助您避開常見陷阱。

規則一：命名空間宣告必須是腳本的第一條敘述

PHP 要求 namespace 關鍵字必須出現在檔案最開頭，前面不能有任何非 PHP 程式碼（包括 HTML 標籤、空白字元、註解、BOM 標記）。

錯誤範例 1：前面有 HTML 標籤

<html>
<?php
namespace MyProject; // 致命錯誤：命名空間必須是第一條敘述
?>

錯誤範例 2：前面有空白行與註解

<?php
// 這裡有註解
// 還有空白行
namespace Foo; // 致命錯誤
class Bar { }
?>

正確寫法

<?php
namespace MyProject;
class Bar { }
?>

規則二：命名空間名稱不可使用 PHP 保留關鍵字

命名空間的各層級名稱（以 \ 分隔）不得為 PHP 關鍵字（如 class、function、abstract、interface 等），否則會導致解析錯誤。

錯誤範例

<?php
namespace Project/Classes/Function; // 解析錯誤：Function 為關鍵字
namespace Project/Abstract/Factory; // 解析錯誤：Abstract 為關鍵字
?>

正確替代

<?php
namespace Project\Classes\Func;      // 避開 Function
namespace Project\AbstractFactory;  // 合併或改用非關鍵字
?>

規則三：命名空間內常數定義的作用域

define() 預設在全域命名空間建立常數。若要在特定命名空間下定義常數，必須在常數名稱前加上命名空間前綴，或使用魔術常數 __NAMESPACE__。

全域常數（預設行為）

<?php
namespace test;
define('MESSAGE', 'Hello world!'); // 實際建立 \MESSAGE
?>

命名空間常數（兩種寫法）

<?php
namespace test;
// 寫法一：手動加前綴
define('test\HELLO', 'Hello world!');
// 寫法二：使用 __NAMESPACE__ 動態取得
define(__NAMESPACE__ . '\GOODBYE', 'Goodbye cruel world!');
?>

呼叫方式對照

<?php
namespace test;
echo MESSAGE;        // 錯誤：找不到 test\MESSAGE，需用 \MESSAGE
echo \MESSAGE;       // 正確：全域常數
echo HELLO;          // 正確：當前命名空間常數
echo \test\HELLO;    // 正確：完整限定名稱
?>

最佳實務建議

• 檔案開頭絕不輸出任何字元，包含 BOM、空白、換行；建議純 PHP 檔案省略結尾 ?>。
• 命名空間層級採用 Vendor\Package\Component 結構，符合 PSR-4 自動載入規範。
• 常數定義統一使用 define(__NAMESPACE__ . '\CONST_NAME', value)，避免硬編碼命名空間字串。
• 搭配 use 導入常用類別/函式/常數，簡化程式碼閱讀。

遵循以上三大規則與最佳實務，即可在專案中穩健使用 PHP 命名空間，避免命名衝突並提升程式碼組織度。