Namespace on recca0120 技術筆記

Strauss：Mozart 的繼承者，WordPress 外掛依賴隔離的更好選擇

Sun, 05 Apr 2026 09:00:00 +0800

如果你看過 Mozart 的介紹，知道它在解決什麼問題：WordPress 外掛共用同一個 PHP process，不同外掛用同一個 library 的不同版本會炸，Mozart 把你的 vendor 依賴加上 namespace 前綴來隔離。

Strauss 從 Mozart fork 出來，解決了幾個 Mozart 的已知限制，現在是社群更推薦的選擇。

Strauss 改了什麼

問題	Mozart	Strauss
`files` autoloader 支援	有限	完整支援
常數前綴（`define()`）	不支援	支援
函式前綴	不支援	v0.21.0 起支援
License 合規	可能有問題	修改 header，保留 license 檔案
預設行為	可能刪原始檔案	非破壞性預設
零設定	需要設定	可以完全不設定
測試覆蓋率	有限	完整 PHPUnit 測試

安裝

推薦：PHAR 方式

1

mkdir bin && touch bin/.gitkeep

在 .gitignore 加上：

1

bin/strauss.phar

在 composer.json 加上 scripts：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "scripts": {
 "prefix-namespaces": [
 "sh -c 'test -f ./bin/strauss.phar || curl -o bin/strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/latest/download/strauss.phar'",
 "@php bin/strauss.phar",
 "@composer dump-autoload"
 ],
 "post-install-cmd": ["@prefix-namespaces"],
 "post-update-cmd": ["@prefix-namespaces"]
 }
}

第一次執行時自動下載 PHAR，之後直接用快取的。

或者 require 進專案

1

composer require --dev brianhenryie/strauss

設定

Strauss 可以完全不設定（零設定），它會從你的 composer.json 自動推斷 namespace 前綴和目標目錄。

需要自訂時，加在 extra.strauss：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


{
 "extra": {
 "strauss": {
 "target_directory": "vendor-prefixed",
 "namespace_prefix": "MyPlugin\\Vendor\\",
 "classmap_prefix": "MyPlugin_",
 "constant_prefix": "MYPLUGIN_",
 "packages": [
 "guzzlehttp/guzzle"
 ],
 "exclude_from_copy": {
 "packages": ["psr/container"],
 "namespaces": ["Psr\\Log\\"],
 "file_patterns": ["\\.md$"]
 },
 "exclude_from_prefix": {
 "namespaces": ["Psr\\"]
 }
 }
 }
}

選項	說明
`target_directory`	處理後的檔案放哪（預設 `vendor-prefixed`）
`namespace_prefix`	加在 namespace 前面的前綴
`classmap_prefix`	沒有 namespace 的 class 前綴
`constant_prefix`	`define()` 常數的前綴
`exclude_from_copy`	不要複製的套件、namespace、檔案
`exclude_from_prefix`	複製但不加前綴（例如 PSR 標準介面）

執行

1

composer prefix-namespaces

或者直接：

1

php bin/strauss.phar

乾跑預覽（不實際修改檔案）：

1

php bin/strauss.phar --dry-run

常數前綴

Mozart 不支援 define() 的前綴，Strauss 支援：

1
2
3
4
5


// 你的依賴裡有
define('GUZZLE_VERSION', '7.0');

// Strauss 改成
define('MYPLUGIN_GUZZLE_VERSION', '7.0');

常數也是全域的，跟 class 一樣會衝突，這個功能對某些套件很重要。

files autoloader 支援

有些套件用 files autoloader（不是 PSR-4，直接 require 檔案），Mozart 對這種支援有限，Strauss 完整處理：

1
2
3
4


// 套件的 composer.json
"autoload": {
 "files": ["src/functions.php"]
}

Strauss 會複製並前綴化這些檔案，確保不漏掉。

在外掛裡載入

1
2
3
4
5
6


// plugin.php
require_once __DIR__ . '/vendor-prefixed/autoload.php';

use MyPlugin\Vendor\GuzzleHttp\Client;

$client = new Client();

或者讓 Strauss 把 autoloader 注入進 vendor/autoload.php：

1

php bin/strauss.phar include-autoloader

這樣只需要 require vendor/autoload.php，不需要另外 require vendor-prefixed/autoload.php。

License 合規

Strauss 在修改的每個檔案 header 加上注記，並保留原始 license 檔案。Mozart 這一塊有疑慮，開源 license 通常要求保留原始聲明，Strauss 直接處理這個問題。

跟 Mozart 設定相容

如果你原本用 Mozart，Strauss 可以直接讀 Mozart 的 extra.mozart 設定，不需要馬上改：

1
2
3
4
5
6
7


{
 "extra": {
 "mozart": {
 "dep_namespace": "MyPlugin\\Dependencies\\"
 }
 }
}

Strauss 會自動識別並套用。

應該選 Mozart 還是 Strauss？

如果是新專案，直接用 Strauss。

如果已經在用 Mozart，遇到以下情況可以考慮遷移：

你的依賴用了 files autoloader
需要 define() 常數前綴
對 license 合規有要求
需要函式前綴（v0.21.0+）

遷移成本不高，Strauss 讀得懂 Mozart 設定，改幾行 scripts 就切換過去了。

小結

Strauss 跟 Mozart 解決同一個問題：WordPress 外掛的依賴衝突。差別在細節：更完整的 autoloader 支援、常數前綴、license 合規、更保守的預設值。

新外掛直接選 Strauss，舊外掛有痛點再考慮遷移。

參考資源

Mozart：WordPress 外掛的 Composer 依賴隔離工具

Sat, 04 Apr 2026 09:00:00 +0800

WordPress 外掛開發有一個獨特的問題：所有外掛跑在同一個 PHP process 裡。

你的外掛用了 guzzlehttp/guzzle 7.0，另一個外掛用了 guzzlehttp/guzzle 6.0。兩個外掛各自 composer install，但最後只有一個版本會被載入——先跑到的那個。如果版本不相容，就直接 fatal error。

這不是你能控制的，因為你不知道用戶裝了哪些外掛。

Mozart 的解法：把你的 vendor 依賴複製一份，全部加上你自己的 namespace 前綴，讓它們跟別人的完全不衝突。

問題的本質

PHP 的 class 是全域的。GuzzleHttp\Client 只能存在一個定義。

Mozart 把它改名成 YourPlugin\Dependencies\GuzzleHttp\Client，這樣就算別人也載入了原版的 GuzzleHttp\Client，兩者完全是不同的 class，互不干擾。

安裝

Mozart 本身有依賴，建議用 Docker 或 PHAR 隔離，避免 Mozart 自己的依賴污染你的 vendor：

1
2
3
4
5
6
7
8


# Docker（推薦）
docker run --rm -it -v ${PWD}:/project/ coenjacobs/mozart /mozart/bin/mozart compose

# 全域安裝（簡單但有風險）
composer global require coenjacobs/mozart

# PHAR
php mozart.phar compose

設定

在 composer.json 的 extra 加上 Mozart 設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
 "extra": {
 "mozart": {
 "dep_namespace": "MyPlugin\\Dependencies\\",
 "dep_directory": "/vendor-prefixed/",
 "classmap_prefix": "MyPlugin_",
 "packages": [
 "guzzlehttp/guzzle",
 "psr/http-client"
 ],
 "excluded_packages": [
 "psr/container"
 ],
 "delete_vendor_directories": true
 }
 }
}

設定說明：

選項	說明
`dep_namespace`	加在所有 namespace 前面的前綴
`dep_directory`	處理後的檔案放哪裡
`classmap_prefix`	沒有 namespace 的 class 加什麼前綴
`packages`	要處理哪些套件（不填就處理全部 require）
`excluded_packages`	排除哪些套件
`delete_vendor_directories`	處理完刪掉 vendor 裡的原始目錄

執行

1
2
3
4
5


# 確認設定正確
mozart config

# 執行前綴化
mozart compose

執行後，vendor-prefixed/ 目錄裡的程式碼全部改好了：

1
2
3
4
5
6
7


// 原本
namespace GuzzleHttp;
use Psr\Http\Client\ClientInterface;

// 處理後
namespace MyPlugin\Dependencies\GuzzleHttp;
use MyPlugin\Dependencies\Psr\Http\Client\ClientInterface;

所有 use 陳述式、型別提示、class_exists() 的字串都一起改，不會有漏網之魚。

搭配 Composer scripts 自動化

1
2
3
4
5
6


{
 "scripts": {
 "post-install-cmd": ["mozart compose"],
 "post-update-cmd": ["mozart compose"]
 }
}

這樣每次 composer install 或 composer update 之後，Mozart 自動執行。

在外掛裡使用

Mozart 處理完之後，你需要載入它產生的 autoloader，不再用原本 vendor 的版本：

1
2
3
4
5
6
7


// plugin.php
require_once __DIR__ . '/vendor-prefixed/autoload.php';

// 之後正常用，但實際載入的是前綴過的版本
use MyPlugin\Dependencies\GuzzleHttp\Client;

$client = new Client();

沒有 namespace 的 class

有些舊套件沒有用 namespace，例如：

1
2


// 原本
class Container { ... }

Mozart 把它改成：

1
2


// 處理後
class MyPlugin_Container { ... }

所有呼叫 new Container() 的地方也一起改成 new MyPlugin_Container()。

限制

不支援動態 class 名稱：如果程式碼裡有這種寫法，Mozart 追蹤不到：

1
2


$class = 'GuzzleHttp\\Client';
$obj = new $class(); // Mozart 不會改這裡

Mozart 自身的依賴問題：Mozart 本身也用了一些 library，如果 require 進專案可能跟你的依賴衝突，所以推薦用 Docker 或 PHAR 執行。

維護狀態：Mozart 還在維護（最新版 1.1.3），但社群已有不少人轉向 Strauss，它是從 Mozart fork 出來的，解決了幾個 Mozart 的已知問題。

小結

WordPress 外掛的依賴衝突問題沒有官方解法，Mozart 是目前最直接的工具。核心概念簡單：把依賴複製一份，namespace 加前綴，讓它跟別人的版本完全不是同一個 class。

如果你遇到 Mozart 的限制（常數前綴、file autoloader 支援、license 合規），可以考慮 Strauss，它在這幾個地方做了改進。

參考資源

Mozart GitHub 儲存庫 — 原始碼與完整設定文件
Strauss：Mozart 的 fork 繼承者 — 解決 Mozart 已知問題的替代方案
Composer 官方文件：extra 欄位 — composer.json 的 extra 設定說明
WordPress 外掛開發：依賴管理最佳實踐 — WordPress 官方外掛開發指引