A tool to prefix namespaces, classnames, and constants in PHP files to avoid autoloading collisions.
A fork of Mozart for Composer for PHP.
Have you ever activated a WordPress plugin that has a conflict with another because the plugins use two different versions of the same PHP library? Strauss is the solution to that problem - it ensures that your plugin's PHP dependencies are isolated and loaded from your plugin rather than loading from whichever plugin's autoloader registers & runs first.
⚠️ Sponsorship: I don't want your money. Please write a unit test to help the project.
- Installation
- As a
.phar
file (recommended) - As a dev dependency via composer (not recommended)
- Adding
composer dump-autoload
- As a
- Usage
- Configuration
- Autoloading
- Motivation & Comparison to Mozart
- Alternatives
- Breaking Changes
- Acknowledgements
There are a couple of small steps to make this possible.
This ensures that there is a bin/
directory in the root of your project. This is where the .phar
file will go.
mkdir bin
touch bin/.gitkeep
Add the following to your .gitignore
:
bin/strauss.phar
In your composer.json
, add strauss
to the scripts
section:
"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",
"@php composer dump-autoload"
],
"post-install-cmd": [
"@prefix-namespaces"
],
"post-update-cmd": [
"@prefix-namespaces"
]
}
This provides composer strauss
, which does the following:
- The
sh -c
command tests ifbin/strauss.phar
exists, and if not, downloads it from releases. - Then
@php bin/strauss.phar
is run to prefix the namespaces. - Ensure that composer's autoload map is updated.
If you prefer to include Strauss as a dev dependency, you can still do so. You mileage may vary when you include it this way.
composer require --dev brianhenryie/strauss
"scripts": {
"prefix-namespaces": [
"strauss",
"@php composer dump-autoload"
],
"post-install-cmd": [
"@prefix-namespaces"
],
"post-update-cmd": [
"@prefix-namespaces"
]
}
If you add Strauss to your composer.json
as indicated in Installation, it will run when you composer install
or composer update
. To run Strauss directly, simply use:
composer prefix-namespaces
To update the files that call the prefixed classes, you can use --updateCallSites=true
which uses your autoload key, or --updateCallSites=includes,templates
to explicitly specify the files and directories.
composer -- prefix-namespaces --updateCallSites=true
or
composer -- prefix-namespaces --updateCallSites=includes,templates
Strauss potentially requires zero configuration, but likely you'll want to customize a little, by adding in your composer.json
an extra/strauss
object. The following is the default config, where the namespace_prefix
and classmap_prefix
are determined from your composer.json
's autoload
or name
key and packages
is determined from the require
key:
"extra": {
"strauss": {
"target_directory": "vendor-prefixed",
"namespace_prefix": "BrianHenryIE\\My_Project\\",
"classmap_prefix": "BrianHenryIE_My_Project_",
"constant_prefix": "BHMP_",
"packages": [
],
"update_call_sites": false,
"override_autoload": {
},
"exclude_from_copy": {
"packages": [
],
"namespaces": [
],
"file_patterns": [
]
},
"exclude_from_prefix": {
"packages": [
],
"namespaces": [
],
"file_patterns": [
]
},
"namespace_replacement_patterns" : {
},
"delete_vendor_packages": false,
"delete_vendor_files": false
}
},
The following configuration is inferred:
target_directory
defines the directory the files will be copied to, defaultvendor-prefixed
namespace_prefix
defines the default string to prefix each namespace withclassmap_prefix
defines the default string to prefix class names in the global namespacepackages
is the list of packages to process. If absent, all packages in therequire
key of yourcomposer.json
are includedclassmap_output
is abool
to decide if Strauss will createautoload-classmap.php
andautoload.php
. If it is not set, it isfalse
iftarget_directory
is in your project'sautoload
key,true
otherwise.
The following configuration is default:
-
delete_vendor_packages
:false
a boolean flag to indicate if the packages' vendor directories should be deleted after being processed. It defaults to false, so any destructive change is opt-in. -
delete_vendor_files
:false
a boolean flag to indicate if files copied from the packages' vendor directories should be deleted after being processed. It defaults to false, so any destructive change is opt-in. This is maybe deprecated! Is there any use to this that is more appropriate thandelete_vendor_packages
? -
include_modified_date
is abool
to decide if Strauss should include a date in the (phpdoc) header written to modified files. Defaults totrue
. -
include_author
is abool
to decide if Strauss should include the author name in the (phpdoc) header written to modified files. Defaults totrue
. -
update_call_sites
:false
. This can betrue
,false
or anarray
of directories/filepaths. When set totrue
it defaults to the directories and files in the project'sautoload
key. The PHP files and directories' PHP files will be updated where they call the prefixed classes.
The remainder is empty:
constant_prefix
is fordefine( "A_CONSTANT", value );
->define( "MY_PREFIX_A_CONSTANT", value );
. If it is empty, constants are not prefixed (this may change to an inferred value).override_autoload
a dictionary, keyed with the package names, of autoload settings to replace those in the original packages'composer.json
autoload
property.exclude_from_prefix
/file_patterns
exclude_from_copy
packages
array of package names to be skippednamespaces
array of namespaces to skip (exact match from the package autoload keys)file_patterns
array of regex patterns to check filenames against (including vendor relative path) where Strauss will skip that file if there is a match
exclude_from_prefix
packages
array of package names to exclude from prefixing.namespaces
array of exact match namespaces to exclude (i.e. not substring/parent namespaces)
namespace_replacement_patterns
a dictionary to use inpreg_replace
instead of prefixing withnamespace_prefix
.
Strauss uses Composer's own tools to generate a classmap file in the target_directory
and creates an autoload.php
alongside it, so in many projects autoloading is just a matter of:
require_once __DIR__ . '/strauss/autoload.php';
If you prefer to use Composer's autoloader, add your target_directory
(default vendor-prefixed
) to your autoload
classmap
and Strauss will not create its own autoload.php
when run. Then run composer dump-autoload
to include the newly copied and prefixed files in Composer's own classmap.
"autoload": {
"classmap": [
"vendor-prefixed/"
]
},
I was happy to make PRs to Mozart to fix bugs, but they weren't being reviewed and merged. At the time of writing, somewhere approaching 50% of Mozart's code was written by me with an additional nine open PRs and the majority of issues' solutions provided by me. This fork is a means to merge all outstanding bugfixes I've written and make some more drastic changes I see as a better approach to the problem.
Benefits over Mozart:
- A single output directory whose structure matches source vendor directory structure (conceptually easier than Mozart's independent
classmap_directory
anddep_directory
) - A generated
autoload.php
toinclude
in your project (analogous to Composer'svendor/autoload.php
) - Handles
files
autoloaders – and any autoloaders that Composer itself recognises, since Strauss uses Composer's own tooling to parse the packages - Zero configuration – Strauss infers sensible defaults from your
composer.json
- No destructive defaults –
delete_vendor_files
defaults tofalse
, so any destruction is explicitly opt-in - Licence files are included and PHP file headers are edited to adhere to licence requirements around modifications. My understanding is that re-distributing code that Mozart has handled is non-compliant with most open source licences – illegal!
- Extensively tested – PhpUnit tests have been written to validate that many of Mozart's bugs are not present in Strauss
- More configuration options – allowing exclusions in copying and editing files, and allowing specific/multiple namespace renaming
- Respects
composer.json
vendor-dir
configuration - Prefixes constants (
define
) - Handles meta-packages and virtual-packages
Strauss will read the Mozart configuration from your composer.json
to enable a seamless migration.
I don't have a strong opinion on these. I began using Mozart because it was easy, then I adapted it to what I felt was most natural. I've never used these.
- humbug/php-scoper
- TypistTech/imposter-plugin
- Automattic/jetpack-autoloader
- tschallacka/wordpress-composer-plugin-builder
- Interfacelab/namespacer
- PHP-Prefixer SaaS!
- v0.16.0 – will no longer prefix PHP built-in classes seen in polyfill packages
- v0.14.0 –
psr/*
packages no longer excluded by default - v0.12.0 – default output
target_directory
changes fromstrauss
tovendor-prefixed
Please open issues to suggest possible breaking changes. I think we can probably move to 1.0.0 soon.
- Comprehensive attribution of code forked from Mozart – changes have been drastic and
git blame
is now useless, so I intend to add more attributions - More consistent naming. Are we prefixing or are we renaming?
- Further unit tests, particularly file-system related
- Regex patterns in config need to be validated
- Change the name? "Renamespacer"?
The correct approach to this problem is probably via PHP-Parser. At least all the tests will be useful.
Coen Jacobs and all the contributors to Mozart, particularly those who wrote nice issues.