Foundation

Foundation is a StellarWP Composer monorepo for reusable PHP packages intended for libraries and WordPress plugin ecosystems.

Note

This monorepo splits each package out into their own sub-repository, if you only need a specific component you can install only that specific one.

Repositories

• stellarwp/foundation-container
• stellarwp/foundation-pipeline
• stellarwp/foundation-log

Installation

composer require stellarwp/foundation

‍💻 Developer / Contributing Documentation

✅ Development requirements

• PHP 8.3+

🧪 Automated testing

Run all tests:

composer test

Run just the unit test suite:

composer test:unit

Run just the feature test suite:

composer test:feature

Generate the test coverage HTML dashboard (XDEBUG required to be enabled on your machine):

composer test:coverage-html

Code Quality

Check your code style:

composer lint

Automatically fix your code style:

composer format

Static analysis:

composer analyze

🥳 Releasing a new version

Before drafting the release, run the monorepo maintenance commands that apply to the release:

Situation	Command	Why
You are planning a major version release, for example 2.0 to 3.0. You should run this so any Foundation packages that depend on each other require the new major line, such as ^3.0. You may also run it for a minor release if one package must require APIs added in that new minor version.	composer monorepo bump-interdependency <version>	Updates package-to-package dependency constraints. Use the new minimum Composer constraint, such as ^3.0 or ^1.2.
The dev-main branch alias needs to move to a new development line, usually after a minor or major release. For example, after releasing 1.1.0, update the alias from 1.1.x-dev to 1.2.x-dev. Do not run this before every patch release if the existing alias is still correct.	composer monorepo package-alias	Updates each package's extra.branch-alias using the format configured in monorepo-builder.php.
Neither of the above changed.	No monorepo maintenance command is needed.	Continue to drafting the release.

After any needed command, commit the updated composer.json files. Then draft a new release on GitHub, following semver closely.

The monorepo split GitHub workflow will deploy each project's code to their sub-repository.

Monorepo

This uses Symplify's Monorepo Builder. There is a shortcut composer script you can run to access their CLI: composer monorepo list to see the available commands.

Adding a New Package

1. Copy the composer.json from one of the packages and modify the name and psr-4 autoload namespace.
2. Ensure you have the close-pull-request.yml GitHub workflow, a .gitattributes, .gitignore and README.md files.
3. Once you've added the specific dependencies your package needs to its composer.json, run composer monorepo merge and then composer update and commit the changes. This will merge the dependencies into the root composer.json.
4. Create your new repository, add the description: [READ ONLY] Subtree split of the Foundation <NEW_COMPONENT_NAME> component (see stellarwp/foundation) and disable wikis, issues, projects and pull requests.

License

Copyright © 2026 Nexcess Corp.

Licensed under the GNU General Public License v2.0 or later. See LICENSE for details.