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.

Functions

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'

get_site_unique_id()

Returns the site's unique anonymous identifier, used for privacy-preserving statistics.

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.

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 Troy: header)
• dependencies — Raw dependencies string (from 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_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

Dependencies can be declared in plugin headers as:

• Troy Dependency: plugin-slug — Uses the plugin's own Troy: header for the repo
• Troy Dependency: plugin-slug <repo-url> — Specifies a different repo URL
• Troy Dependencies: slug-one, slug-two <custom-repo> — Multiple dependencies

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

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.

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.com
  • sub.example.com/repo/path
  • localhost/repo
  • https://example.com/ (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.com/path' );
// Returns: 'https://repo.example.com/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.

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.

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: 15 seconds (hardcoded floor)

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

Plugin Headers

These headers are recognized in plugin files:

Troy

Registers the plugin with a Troy Server for updates.

/**
 * Plugin Name: My Plugin
 * Troy: repo.example.com
 */

Troy Dependency / Troy Dependencies

Declares plugin dependencies that should be fetched from Troy Servers.

/**
 * Plugin Name: My Plugin
 * Troy: repo.example.com
 * Troy Dependencies: required-plugin, another-plugin <other-repo.com>
 */

disable-all-communications

Prevents all external communication about the plugin.

/**
 * Plugin Name: My Private Plugin
 * Troy: disable-all-communications
 */

This hides the plugin from WordPress.org and prevents any Troy Server from receiving information about it.