strauss-setup.md

Setting up Strauss in your project

Strauss is a library for creating namespaced classes and constants on other libraries included within a WordPress project. This way, if your WordPress project is run alongside another WordPress project that has overlapping dependencies, they won't actually conflict!

Adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency.

• Including Strauss
  • As a .phar file
  • As a dev dependency via composer (not recommended)
• Adding your configuration
• Ensuring auto-running of Strauss
• Add the Strauss autoloader
• Tell PHPStan about your vendor/vendor-prefixed directory

Including Strauss

As a .phar file

To reduce the potentials for conflicts while using Strauss in your project, it is recommended that Straus is added to your project as a .phar file during the build process. There are a couple of small steps to make this possible.

Create a bin/.gitkeep file

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

.gitignore the .phar file

Add the following to your .gitignore:

bin/strauss.phar

Create a composer.json scripts entry for Strauss

In your composer.json, add strauss to the scripts section:

"scripts": {
	"strauss": [
		"test -f ./bin/strauss.phar || curl -o bin/strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/download/0.18.0/strauss.phar",
		"@php bin/strauss.phar"
                "@php composer dump-autoload"
	]
}

As a dev dependency via composer (not recommended)

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

Create a composer.json scripts entry for Strauss

In your composer.json, add strauss to the scripts section:

"scripts": {
	"strauss": [
		"vendor/bin/strauss"
	]
}

Adding your configuration

There are a number of configuration settings that might be useful for your project, however, the following is the suggested configuration for this library at a minimum. Add the following to your composer.json file:

"extra": {
	"strauss": {
		"target_directory": "vendor/vendor-prefixed",
		"namespace_prefix": "Boom\\Shakalaka\\",
		"classmap_prefix": "Boom_Shakalaka_",
		"constant_prefix": "BOOM_SHAKALAKA_",
		"delete_vendor_packages": true,
		"packages": [
			"stellarwp/REPO_NAME"
		],
		"include_modified_date": false,
		"include_author": false
	}
},

When Strauss is run, this configuration will cause it to execute for the stellarwp/REPO_NAME package and all of its dependencies, placing them inside of the vendor/vendor-prefixed directory in your project.

Note: The exclude_from_prefix argument in the strauss configuration can be used to avoid issues with packages you don't want to prefix with your project's namespace. Previously this was used to fix issues with PSR packages, but Strauss has removed that exclusion since v0.14.0.

Ensuring auto-running of Strauss

Adding the following to your composer.json file will ensure that Strauss is run automatically when composer install or update is excecuted:

"scripts": {
	"post-install-cmd": [
			"@strauss"
	],
	"post-update-cmd": [
			"@strauss"
	]
}

Additionally, you can run this manually via composer run strauss.

Add the Strauss autoloader

You'll need to add the Strauss autoloader to your project so that all of the relevant classes are available. If you were to put it in a WordPress plugin's bootstrap file (the main file in the base directory of your plugin), you'd add a line like so:

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

Tell PHPStan about your vendor/vendor-prefixed directory

PHPStan doesn't know about your vendor/vendor-prefixed directory by default. Luckily, you can add a scanDirectories to parameters in your phpstan.neon.dist file and you'll be good to go!

Here's an example:

parameters:
	scanDirectories:
		- vendor/vendor-prefixed