Troy Client API Reference

Troy Client exposes a public API for developers who want to integrate with or extend its functionality. All public functions are in the Troy\Client namespace.

Plugin Discovery

These functions identify which installed plugins are Troy-enabled and extract their metadata. For background on how Troy Client detects plugins, see How It Works. For header syntax, see Plugin Headers.

get_troy_plugins()

Returns all installed plugins that have Troy headers.

Troy\Client\get_troy_plugins(): array

Returns: An associative array keyed by plugin file (basename), containing:

• slug — The plugin's slug.
• name — The plugin's display name.
• version — The current version.
• textdomain — The plugin's text domain.
• repo — The Troy server URL (from the Troy header).
• dependencies — Raw dependencies string (from the Troy Dependencies header).

Example:

$plugins = Troy\Client\get_troy_plugins();
foreach ( $plugins as $file => $plugin ) {
    echo "{$plugin['name']} v{$plugin['version']} updates from {$plugin['repo']}";
}

has_troy_plugins()

Checks whether the site has any Troy-enabled plugins (excluding Troy Client itself).

Troy\Client\has_troy_plugins(): bool

Returns: true if Troy-enabled plugins are installed, false otherwise.

get_plugin_slug()

Converts a plugin file path to its slug.

Troy\Client\get_plugin_slug( string $plugin_file ): string

Parameters:

• $plugin_file — The plugin file relative to the plugins directory (e.g., my-plugin/my-plugin.php).

Returns: The plugin's slug (e.g., my-plugin).

Example:

$slug = Troy\Client\get_plugin_slug( 'my-plugin/my-plugin.php' );
// Returns: 'my-plugin'

Routing & Dependencies

These functions map plugins to their Troy Servers and resolve dependency chains. For dependency declaration syntax, see Troy Dependencies.

get_troy_plugin_repos_per_slug()

Returns a mapping of plugin slugs to their Troy server URLs.

Troy\Client\get_troy_plugin_repos_per_slug(): array

Returns: An associative array where keys are plugin slugs and values are fully-qualified repository URLs.

Includes both direct Troy registrations and dependencies from Troy Dependencies headers.

get_troy_plugin_slugs_per_repo()

Returns a mapping of Troy server URLs to their associated plugin slugs.

Troy\Client\get_troy_plugin_slugs_per_repo(): array

Returns: An associative array where keys are repository URLs and values are arrays of plugin slugs.

Useful for batching update requests to the same server.

get_troy_plugin_dependencies()

Returns parsed dependency information for all Troy plugins.

Troy\Client\get_troy_plugin_dependencies(): array

Returns: An associative array keyed by plugin file, containing:

• slug — The plugin's slug.
• dependencies — Array of dependency objects with slug and repo keys.

Limits: Maximum 5 dependencies per plugin; headers limited to 191 characters.

recheck_dependencies()

Gets or sets whether Troy Client should recheck plugin dependencies.

Troy\Client\recheck_dependencies( ?string $recheck = null ): bool

Parameters:

• $recheck — 'yes' or 'no' to set the value, or null to get current value.

Returns: true if dependencies should be rechecked, false otherwise.

Server Requests

These functions build URLs and send requests to Troy Servers. For details on caching and the privacy model, see How It Works.

make_fully_qualified_repo_url()

Converts a bare repository URL to a fully-qualified HTTPS URL.

Troy\Client\make_fully_qualified_repo_url( string $repo ): string

Parameters:

• $repo — A repository URL in any of these formats:
  • example.org
  • sub.example.org/repo/path
  • localhost/repo
  • https://example.org/ (scheme will be normalized)

Returns: A fully-qualified URL with https:// scheme and trailing slash.

Example:

$url = Troy\Client\make_fully_qualified_repo_url( 'repo.example.org/path' );
// Returns: 'https://repo.example.org/path/'

make_troy_api_request()

Makes a direct API request to a Troy Server.

Troy\Client\make_troy_api_request(
    string $repo,
    array|string $body = '',
    string $method = 'POST'
): array|WP_Error

Parameters:

• $repo — The Troy Server endpoint URL.
• $body — Request body (array for JSON, string for raw).
• $method — HTTP method (GET or POST).

Returns: WordPress HTTP response array or WP_Error on failure.

Automatically includes Troy Client headers (X-Troy-Client-Id, User-Agent).

make_troy_api_request_cached()

Makes a cached API request to a Troy Server.

Troy\Client\make_troy_api_request_cached(
    string $key,
    string $repo,
    array|string $body = '',
    string $method = 'POST'
): array|WP_Error

Parameters:

• $key — Cache key for this request.
• $repo — The Troy Server endpoint URL.
• $body — Request body (array for JSON, string for raw).
• $method — HTTP method (GET or POST).

Returns: WordPress HTTP response array or WP_Error on failure.

Cache expires based on the Troy\Client\API_TIMEOUT constant (default: 10 minutes). Errors are not cached but are memoized within a request to prevent rapid re-requests.

get_site_unique_id()

Returns the site's unique anonymous identifier, sent with every API request.

Troy\Client\get_site_unique_id(): string

Returns: A unique ID string in the format {epoch}-{random_hex}.

The ID rotates every week (epoch changes weekly), ensuring anonymous usage tracking without persistent identification.

Constants

Troy Client behavior can be customized via PHP constants. Define these in wp-config.php or a must-use plugin.

HIDE

Hides Troy Client from the WordPress plugins list.

define( 'Troy\Client\HIDE', true );

Use this for managed hosting or white-label scenarios where end users shouldn't interact with Troy Client directly.

CHANNEL

Sets the update channel for all Troy plugins.

define( 'Troy\Client\CHANNEL', 'beta' );

Values:

• 'tag' (default) — Only receive stable tagged releases
• 'beta' — Receive beta releases in addition to stable releases

When set to 'beta', Troy Client requests both stable and beta versions from Troy Servers, installing whichever is newer.

API_TIMEOUT

Sets the cache duration for API responses in seconds.

define( 'Troy\Client\API_TIMEOUT', 300 ); // 5 minutes

Default: 600 (10 minutes) Minimum: 30 seconds (hardcoded floor)

Lower values mean more frequent update checks but increased server load.

Plugin Headers

Troy Client recognizes several plugin headers (Troy, Troy Dependencies, and special values like disable-all-communications). For the full reference, see Plugin Headers.