API Reference

Troy Server exposes public REST endpoints for plugin distribution and PHP API classes for server-side integrations.

Constants

Troy Server defines these constants in the Troy\Server namespace:

REST Endpoints

All endpoints are relative to your Troy Server URL (e.g., https://repo.deploytroy.org/).

Ping

GET /ping

Returns server status. Useful for connectivity checks.

Response: 200 OK

{"status":"ok","message":"pong","time":"loading..."}

Plugin Updates

POST /plugin/get/updates

Check for available plugin updates. This is the primary endpoint Troy Client calls.

Request Body (JSON):

{
  "active_plugins": {
    "my-plugin/my-plugin.php": "1.0.0"
  },
  "inactive_plugins": {},
  "php_version": "8.2",
  "wp_version": "6.8",
  "troy_version": "0.0.1184",
  "channel": "tag",
  "locales": ["en_US"]
}

Response:

{
  "update": {
    "my-plugin": {
      "id": "repo.deploytroy.org",
      "slug": "my-plugin",
      "new_version": "1.1.0",
      "url": "https://example.com/my-plugin",
      "package": "https://repo.deploytroy.org/plugin/get/zip/my-plugin/1.1.0/",
      "icons": { "1x": "" },
      "banners": [],
      "banners_rtl": [],
      "requires": "6.7",
      "tested": "6.8",
      "requires_php": "7.4",
      "requires_plugins": [],
      "compatibility": [],
      "upgrade_notice": "",
      "autoupdate": false
    }
  },
  "no_update": {},
  "translations": []
}

Plugin Information

GET /plugin/get/info?slug={slug}

Get detailed plugin information for the WordPress plugin modal.

Plugin Download

GET /plugin/get/zip/{slug}
GET /plugin/get/zip/{slug}/{version}

Download a plugin ZIP file. Without {version}, returns the latest stable release.

Package Download

GET /package/get/zip/{slug}

Download a Troy Package (installer bundle).

Channels

The channel parameter in update requests:

PHP API Classes

Troy Server provides API classes in the Troy\Server\API namespace for developers building integrations or extending functionality.

Server Class

Server-wide operations and configuration.

use Troy\Server\API\Server;

get_db_version()

Returns the current database version.

Server::get_db_version(): int

get_repo_url()

Returns the bare repository URL (without scheme).

Server::get_repo_url(): string
// Returns: 'example.com/repo'

get_full_repo_url()

Returns the fully-qualified repository URL.

Server::get_full_repo_url(): string
// Returns: 'https://example.com/repo/'

get_server_settings()

Returns the plugin settings array.

Server::get_server_settings(): array

Plugin Class

Plugin lookup and management operations.

use Troy\Server\API\Plugin;

get_plugin_id_by_slug()

Finds a plugin's internal ID by its slug.

Plugin::get_plugin_id_by_slug( string $slug ): ?int

Returns: The plugin ID or null if not found.

get_plugin_id_by_post_id()

Finds a plugin's internal ID by its WordPress post ID.

Plugin::get_plugin_id_by_post_id( int $post_id ): ?int

get_post_id_by_plugin_id()

Finds the WordPress post ID for a plugin.

Plugin::get_post_id_by_plugin_id( int $plugin_id ): ?int

Package Class

Package lookup operations.

use Troy\Server\API\Package;

get_package_id_by_slug()

Finds a package's internal ID by its slug.

Package::get_package_id_by_slug( string $slug ): ?int

get_package_id_by_post_id()

Finds a package's internal ID by its WordPress post ID.

Package::get_package_id_by_post_id( int $post_id ): ?int

get_post_id_by_package_id()

Finds the WordPress post ID for a package.

Package::get_post_id_by_package_id( int $package_id ): ?int

Sanitize Class

Input sanitization utilities.

use Troy\Server\API\Sanitize;

semver()

Extracts and sanitizes a SemVer version string.

Sanitize::semver( string $version ): string

Requires three-part versioning (major.minor.patch). Returns empty string if invalid.

slug()

Sanitizes a slug for URLs and database storage.

Sanitize::slug( string $slug ): string

• Converts to lowercase
• Replaces non-alphanumeric characters with hyphens
• Collapses multiple hyphens
• Limits to 191 characters

sql_date()

Sanitizes a date for SQL storage.

Sanitize::sql_date( string $date ): string
// Returns: 'Y-m-d' format

bare_repo_url()

Strips a URL to its bare form (no scheme, no trailing slash).

Sanitize::bare_repo_url( string $url ): string

fully_qualified_repo_url()

Reconstructs a full HTTPS URL from a bare URL.

Sanitize::fully_qualified_repo_url( string $url ): string

file_path()

Sanitizes a file path for safe storage and retrieval.

Sanitize::file_path( string $file_path ): string

docblock_content()

Sanitizes content extracted from docblocks (plugin headers, etc.).

Sanitize::docblock_content( string $value ): string

var_export()

Exports a variable to a formatted string representation.

Sanitize::var_export( mixed $value, int $tab_count = 0 ): string

Useful for generating PHP code from dynamic values.

Utils Class

General utilities.

use Troy\Server\API\Utils;

get_epoch()

Returns the current or previous epoch for UUID rotation.

Utils::get_epoch( string $offset = 'current' ): int

Parameters:

• $offset — 'current' or 'last' for previous epoch

Epochs rotate weekly, used for anonymous client identification.

extract_latest_version()

Finds the latest version from an array of version objects.

Utils::extract_latest_version( array $versions ): ?string

Prioritizes by type: tag > beta > unreleased.

get_latest_public_wordpress_version()

Returns the latest public WordPress version (from GitHub API).

Utils::get_latest_public_wordpress_version( string $from_version = '' ): string

Results are cached for 6 hours.

Slug Class

Slug conflict detection and resolution.

use Troy\Server\API\Slug;

Unlike other API classes, Slug is instantiated:

$slug = new Slug(
    slug: 'my-plugin',
    for_type: 'plugin',  // 'plugin' or 'package'
    exclude_id: 0        // ID to exclude from conflict checks
);

// Properties (read-only, lazily computed)
$slug->conflict_type;  // 'plugin', 'package', or null
$slug->unique_slug;    // Original slug or suffixed version

Source Code

For implementation details, see the Troy Server source:

• API Classes
• REST Endpoints