Dependencies
If your plugin requires another plugin to function, you can declare it via the Troy Dependencies header. Troy Client will auto-install missing dependencies in the background, without prompts or confirmation dialogs.
Prefer Packages for distribution:
The auto-install behavior is a convenience fallback — it's not a distribution strategy. Plugins should stand on their own. If yours genuinely requires another plugin, declare it so Troy Client can install it — but explain the dependency to your users. For a controlled first-install experience, use Packages instead.
Declaring Dependencies
Single dependency:
/**
* Troy: repo.example.org
* Troy Dependency: required-plugin
*/
Multiple dependencies:
/**
* Troy: repo.example.org
* Troy Dependencies: plugin-one, plugin-two
*/
Dependencies from a different server:
/**
* Troy: repo.example.org
* Troy Dependencies: same-server-plugin, other-server-plugin <other-server.org>
*/
When no <server-URL> is specified, the dependency inherits the parent plugin's Troy header server. Every dependency that lives on a different server must specify its own URL wrapped in angle brackets — the < and > are required syntax, not optional. The URL formats from the Troy header apply to server annotations as well.
Both Troy Dependency: and Troy Dependencies: are accepted. Use whichever reads better.
Limits
- A plugin may declare up to 5 dependencies.
- Troy dependencies must be hosted on a Troy Server (or one that implements the same API). WordPress.org plugins cannot be Troy dependencies.
- There are no version constraints in the header syntax — Troy Client always installs the latest available version. Update checks respect PHP and WordPress version requirements, but dependency installs do not.
- Both headers have a 191-character limit. The limit is enforced server-side to keep database indexing fast.
What Happens When a Dependency Is Missing
- Troy Client detects the missing dependency on the next admin page load.
- Troy Client downloads and installs the dependency in the background.
- The dependency is not activated — the user decides when to activate it.
- An admin notice confirms what was installed, or reports a failure.
If a newly installed plugin declares its own dependencies, Troy Client picks those up on the next admin page load. Each install triggers a fresh scan of all plugin headers — so nested dependencies are discovered and installed one layer at a time, across successive page loads, until no new missing dependencies are found. After a failed install, Troy Client sets a 60-second cooldown before retrying. This cooldown is global — it pauses all dependency resolution, not just the one that failed.
Dependencies without a Troy header:
If your plugin declares a Troy Dependencies header but has no Troy header, every dependency must include an explicit <server>. Troy Client skips dependencies without one and triggers a PHP warning — resolve these before releasing your plugin.
disable-all-communications:
If the Troy header is set to disable-all-communications, Troy Client ignores all declared dependencies for that plugin.
Best Practices
Only declare dependencies your plugin cannot function without. Optional enhancements should not be dependencies.
Consider: would you rather ask your users to install three extra plugins, or bundle the 50 lines of code you actually need?
