Namespace on recca0120 Tech Notes

Strauss: The Better Mozart for WordPress Plugin Dependency Isolation

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

If you’ve read the Mozart overview, you know what problem it solves: WordPress plugins share a PHP process, two plugins using different versions of the same library causes fatal errors, and Mozart prefixes your vendor namespaces to isolate them.

Strauss was forked from Mozart to address several of its known limitations. It’s what the community generally recommends now.

What Strauss Changed

Issue	Mozart	Strauss
`files` autoloader support	Limited	Full
Constant prefixing (`define()`)	Not supported	Supported
Function prefixing	Not supported	v0.21.0+
License compliance	Questionable	Header edits + license files preserved
Destructive defaults	Can delete files	Non-destructive by default
Zero config	Requires setup	Works out of the box
Test coverage	Limited	Comprehensive PHPUnit tests

Installation

Recommended: PHAR

1

mkdir bin && touch bin/.gitkeep

Add to .gitignore:

1

bin/strauss.phar

Add to 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"]
 }
}

Downloads the PHAR on first run, uses the cached version after.

Or Require Directly

1

composer require --dev brianhenryie/strauss

Configuration

Strauss works with zero configuration — it infers the namespace prefix and target directory from your composer.json automatically.

To customize, add 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\\"]
 }
 }
 }
}

Option	Purpose
`target_directory`	Where processed files go (default: `vendor-prefixed`)
`namespace_prefix`	Prefix added to namespaces
`classmap_prefix`	Prefix for classes without namespaces
`constant_prefix`	Prefix for `define()` constants
`exclude_from_copy`	Packages, namespaces, or file patterns to skip entirely
`exclude_from_prefix`	Copy but don’t prefix (e.g. PSR interfaces)

Running

1

composer prefix-namespaces

Or directly:

1

php bin/strauss.phar

Dry run to preview changes without writing:

1

php bin/strauss.phar --dry-run

Constant Prefixing

Mozart doesn’t handle define(). Strauss does:

1
2
3
4
5


// In your dependency
define('GUZZLE_VERSION', '7.0');

// After Strauss
define('MYPLUGIN_GUZZLE_VERSION', '7.0');

Constants are global just like classes — they conflict the same way. This matters for certain packages.

files Autoloader Support

Some packages use files autoloaders (direct require instead of PSR-4). Mozart handles these inconsistently. Strauss processes them fully:

1
2
3
4


// Package's composer.json
"autoload": {
 "files": ["src/functions.php"]
}

Strauss copies and prefixes these files without missing anything.

Loading in Your Plugin

1
2
3
4
5
6


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

use MyPlugin\Vendor\GuzzleHttp\Client;

$client = new Client();

Or have Strauss inject the autoloader into vendor/autoload.php:

1

php bin/strauss.phar include-autoloader

Then you only need require vendor/autoload.php — no separate require for vendor-prefixed/.

License Compliance

Strauss adds a note to each modified file’s header and preserves original license files. Mozart’s handling of this is questionable — open source licenses typically require retaining original attribution. Strauss deals with it properly.

Mozart Configuration Compatibility

If you’re currently using Mozart, Strauss reads extra.mozart config directly. No need to migrate immediately:

1
2
3
4
5
6
7


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

Strauss recognizes and applies it automatically.

Mozart or Strauss?

New project: use Strauss.

Existing Mozart project, consider migrating if:

Your dependencies use files autoloaders
You need define() constant prefixing
License compliance matters
You need function prefixing (v0.21.0+)

Migration cost is low — Strauss reads Mozart config, so it’s mostly updating the scripts section.

Summary

Strauss and Mozart solve the same problem: WordPress plugin dependency conflicts. The difference is in the details: more complete autoloader support, constant prefixing, proper license handling, and safer defaults.

Start new plugins with Strauss. Migrate existing Mozart setups when you hit a limitation.

References

Mozart: Isolate Composer Dependencies in WordPress Plugins

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

WordPress plugin development has a unique problem: all plugins run in the same PHP process.

Your plugin uses guzzlehttp/guzzle 7.0. Another plugin uses guzzlehttp/guzzle 6.0. Both run composer install independently, but only one version gets loaded at runtime — whichever plugin’s autoloader registers first. If the versions are incompatible, you get a fatal error.

You can’t control this, because you don’t know what else your users have installed.

Mozart’s solution: copy your vendor dependencies and add your own namespace prefix to everything, making them completely distinct from anyone else’s copy.

The Core Problem

PHP classes are global. GuzzleHttp\Client can only have one definition.

Mozart renames it to YourPlugin\Dependencies\GuzzleHttp\Client. Even if someone else loads the original GuzzleHttp\Client, they’re now entirely separate classes that don’t interfere with each other.

Installation

Mozart has its own dependencies. Use Docker or a PHAR to keep Mozart isolated from your project’s vendor:

1
2
3
4
5
6
7
8


# Docker (recommended)
docker run --rm -it -v ${PWD}:/project/ coenjacobs/mozart /mozart/bin/mozart compose

# Global install (simpler, but risky)
composer global require coenjacobs/mozart

# PHAR
php mozart.phar compose

Configuration

Add Mozart config to extra in composer.json:

 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
 }
 }
}

Option	Purpose
`dep_namespace`	Prefix added to all namespaces
`dep_directory`	Where processed files go
`classmap_prefix`	Prefix for classes without namespaces
`packages`	Which packages to process (all require entries if omitted)
`excluded_packages`	Packages to skip
`delete_vendor_directories`	Remove original vendor directories after processing

Running

1
2
3
4
5


# verify config
mozart config

# run prefixing
mozart compose

After running, vendor-prefixed/ contains the rewritten code:

1
2
3
4
5
6
7


// Before
namespace GuzzleHttp;
use Psr\Http\Client\ClientInterface;

// After
namespace MyPlugin\Dependencies\GuzzleHttp;
use MyPlugin\Dependencies\Psr\Http\Client\ClientInterface;

All use statements, type hints, and string references in class_exists() calls are updated together.

Automating With Composer Scripts

1
2
3
4
5
6


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

Mozart runs automatically after every composer install or composer update.

Using the Prefixed Code in Your Plugin

After Mozart processes dependencies, load its generated autoloader instead of the original vendor one:

1
2
3
4
5
6
7


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

// Then use normally — the prefixed version loads transparently
use MyPlugin\Dependencies\GuzzleHttp\Client;

$client = new Client();

Classes Without Namespaces

Some older packages don’t use namespaces:

1
2


// Before
class Container { ... }

Mozart prefixes the class name:

1
2


// After
class MyPlugin_Container { ... }

All new Container() call sites are updated to new MyPlugin_Container() as well.

Limitations

Dynamic class names: Mozart can’t track this pattern:

1
2


$class = 'GuzzleHttp\\Client';
$obj = new $class(); // not rewritten

Mozart’s own dependencies: Mozart itself uses libraries. Requiring it directly into your project can cause the same conflicts you’re trying to solve — hence the Docker or PHAR recommendation.

Ecosystem shift: Mozart is still maintained (latest: 1.1.3), but many developers have moved to Strauss, a fork that addresses a few known Mozart limitations — better constant prefixing, full files autoloader support, and license compliance handling.

Summary

There’s no official WordPress solution for dependency conflicts. Mozart is the most direct approach: copy dependencies, prefix namespaces, make your classes completely distinct from everyone else’s.

If you run into Mozart’s limitations — constant prefixing, file autoloaders, license headers — Strauss is worth a look.

References

Mozart GitHub Repository — Source code and full configuration documentation
Strauss: The Mozart Fork — Drop-in replacement that addresses known Mozart limitations
Composer Docs: the extra field — How to configure tools via composer.json extra
WordPress Plugin Development: Best Practices — Official WordPress plugin development guidelines