Plugin Headers

WordPress plugins carry metadata in two places: the plugin file (PHP docblock headers) and a readme file (text headers and content sections). Troy Server reads both when processing uploads.

Header Reference

Full Example

Plugin File

<?php
/**
 * My Plugin Name
 *
 * @package   Company\MyPluginName
 * @author    J Doe
 * @copyright 2026 J Doe, Company (https://example.org/)
 * @license   MIT
 *
 * @troy-repo
 * Troy: repo.example.org
 *
 * @wordpress-plugin
 * Plugin Name: My Plugin Name
 * Plugin URI: https://example.org/my-plugin
 * Description: This is a short description of my plugin.
 * Version: 1.3.0
 * Author: J Doe
 * Author URI: https://example.org/
 * License: MIT
 * Text Domain: my-plugin-slug
 * Requires at least: 6.8
 * Tested up to: 6.9
 * Requires PHP: 7.4
 */

Readme File (Troy-only)

=== My Plugin Name ===
Homepage URL: https://example.org/
Support URI: https://example.org/support
Donate link: https://github.com/sponsors/example
Locale: en_US
Short Description: This is an example plugin that demonstrates the proper format.

== Description ==

A word about my plugin...

Readme File (WordPress.org Compatible)

If you also publish on WordPress.org, include their required headers. Note that Short Description is gone — the text before == Description == serves the same purpose on WordPress.org, and Troy reads both.

=== My Plugin Name ===
Homepage URL: https://example.org/
Support URI: https://example.org/support
Donate link: https://github.com/sponsors/example
Locale: en_US
Contributors: WordPressOrgUserHandle
Tags: example, demo, sample
Requires at least: 6.8
Tested up to: 6.9
Requires PHP: 7.4.0
Stable tag: 1.2.3
License: GPLv3
License URI: http://www.gnu.org/licenses/gpl-3.0.html

This is an example plugin that demonstrates the proper format.

== Description ==

A word about my plugin...

How Troy Client Processes Headers

Troy Client hooks into WordPress's plugin update and information APIs. It:

1. Scans all installed plugins for Troy headers.
2. Groups plugins by server.
3. Checks each server for updates — sending only that server's plugins, never cross-server data.
4. Omits Troy-enabled plugins from WordPress.org requests.

That last point about omission matters: WordPress.org won't see Troy-enabled plugins, improving privacy and supply chain security.

Troy Header

The Troy header points to your Troy Server:

/**
 * Plugin Name: My Plugin
 * Version: 1.3.0
 * Troy: repo.example.org
 */

Troy Client reads this and checks https://repo.example.org/ for updates.

URL Formats

All of these work:

Schemes are stripped and replaced with HTTPS. Trailing slashes are normalized. The header value must not exceed 191 characters — this limit exists to keep Troy Server's database indexes fast.

Special Value

Troy: disable-all-communications

This value removes your plugin from all external API requests, including WordPress.org. Dependencies declared by this plugin are also ignored. Use this for private plugins you don't want exposed anywhere.

Troy Dependencies Header

The Troy Dependencies header declares plugins your plugin requires. Troy Client auto-installs missing dependencies in the background, without prompts or confirmation dialogs.

Declaring Dependencies

/**
 * Plugin Name: My Plugin
 * Troy: repo.example.org
 * Troy Dependencies: same-server-plugin, other-server-plugin <other-server.org>
 */

Syntax

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.

Plugin Dependency Flow

1. Troy Client detects the missing dependency on the next admin page load.
2. Troy Client downloads and installs the dependency in the background.
3. The dependency is not activated — the user decides when to activate it.
4. 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.

Dependency Header 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.