Aternos/php-spigot-api

An API client for the SpigotMC API written in PHP. This client is a combination of code generated by OpenAPI Generator and thin wrappers to improve usability. It builds upon the XenforoResourceManagerAPI and uses its OpenAPI specification.

The generated code can be found in src/Api and src/Model. It is recommended to use the wrappers in src/Client instead of the generated code.

Requirements

• PHP 8.3 or newer
• PHP extensions: curl, json, mbstring

Installation

Install the package via composer:

composer require aternos/spigot-api

Usage

The main entry point for the API is the SpigotAPIClient class.

<?php
use Aternos\SpigotApi\Client\SpigotAPIClient;

// create an API client (main entry point)
$spigotClient = new SpigotAPIClient();

// set a user agent identifying your application (recommended)
$spigotClient->setUserAgent("my-app/1.0.0 (contact@example.com)");

User Agent

It is recommended to set a user agent that identifies your application, ideally including contact information. If you don't set a user agent, the client sends its own user agent including the installed version, e.g. aternos/php-spigot-api/2.4.0. A user agent set with setUserAgent() replaces it.

Error Handling

All methods that send a request throw an Aternos\SpigotApi\ApiException if the request fails. The exception code is the HTTP status code of the response.

use Aternos\SpigotApi\ApiException;

try {
    $project = $spigotClient->getProject(2);
} catch (ApiException $e) {
    echo $e->getCode() . PHP_EOL;
    var_dump($e->getResponseBody());
}

Custom HTTP Client or Configuration

You can pass your own Aternos\SpigotApi\Configuration and Guzzle client, e.g. to set timeouts or add middlewares:

use Aternos\SpigotApi\Configuration;
use GuzzleHttp\Client;

$spigotClient = new SpigotAPIClient(new Configuration(), new Client(["timeout" => 10]));
// or
$spigotClient->setHttpClient(new Client(["timeout" => 10]));

Result Lists

Most methods return a paginated result list containing the current page of results and navigation helpers. The result list implements Iterator, ArrayAccess and Countable so it can be used like an array. It also has a getResults() method returning the underlying array. The API does not return the total number of results, so getNextPage() returns an empty list after the last page.

listProjects()

XenforoResourceManagerAPI#listResources

To list all projects (resources) on SpigotMC (paginated) for a given page, use listProjects().

Parameters

• int $page = 1. Optional. Default: 1. The page number to retrieve. Items are paginated at 10 results per page.
• ?ProjectOrder $order = null. Optional. Default: null (API default: id). The field to order the results by. From Aternos\SpigotApi\Client\ProjectOrder enum.
• ?SortDirection $direction = null. Optional. Default: null (API default: asc). The direction to order the results by. From Aternos\SpigotApi\Client\SortDirection enum.

use Aternos\SpigotApi\Client\ProjectOrder;
use Aternos\SpigotApi\Client\SortDirection;

$projects = $spigotClient->listProjects(1);

foreach ($projects as $project) {
    // wrappers expose underlying model via getData()
    echo $project->getData()->getTitle() . PHP_EOL;
}

$projects = $projects->getNextPage();

foreach ($projects as $project) {
    echo $project->getData()->getTitle() . PHP_EOL;
}

// list the most downloaded projects
// the order is kept when navigating with getNextPage() / getPreviousPage()
$projects = $spigotClient->listProjects(1, ProjectOrder::DOWNLOAD_COUNT, SortDirection::DESC);

listProjectsForCategory()

XenforoResourceManagerAPI#listResources

To list all projects (resources) on SpigotMC (paginated) for a given category and page, use listProjectsForCategory().

Parameters

• Category $category. Required. The category to filter by. From Aternos\SpigotApi\Client\Category enum.
• int $page = 1. Optional. Default: 1. The page number to retrieve. Items are paginated at 10 results per page.
• ?ProjectOrder $order = null. Optional. Default: null (API default: id). The field to order the results by. From Aternos\SpigotApi\Client\ProjectOrder enum.
• ?SortDirection $direction = null. Optional. Default: null (API default: asc). The direction to order the results by. From Aternos\SpigotApi\Client\SortDirection enum.

use Aternos\SpigotApi\Client\Category;
use Aternos\SpigotApi\Client\ProjectOrder;
use Aternos\SpigotApi\Client\SortDirection;

$projects = $spigotClient->listProjectsForCategory(Category::SPIGOT, 1);

foreach ($projects as $project) {
    // wrappers expose underlying model via getData()
    echo $project->getData()->getTitle() . PHP_EOL;
}

$projects = $projects->getNextPage();

foreach ($projects as $project) {
    echo $project->getData()->getTitle() . PHP_EOL;
}

// list the most recently updated projects in a category
$projects = $spigotClient->listProjectsForCategory(Category::SPIGOT, 1, ProjectOrder::LAST_UPDATE, SortDirection::DESC);

Projects / Resources

getProject()

XenforoResourceManagerAPI#getResource

To get a single project (resource) by its numeric id, use getProject().

Parameters

• int $id. Required. The numeric id of the project.

// get a specific project (by numeric id)
$project = $spigotClient->getProject(2);

// get data from the wrapper
$id = $project->getData()->getId();
$title = $project->getData()->getTitle();
$description = $project->getData()->getDescription();

More information

To request more information about a project from the API, use the methods on the Project wrapper.

use Aternos\SpigotApi\Client\SortDirection;
use Aternos\SpigotApi\Client\VersionOrder;

// get a specific project (by numeric id)
$project = $spigotClient->getProject(2);

// fetch the versions from the API as a PaginatedVersionList (sends a request)
$versions = $project->fetchVersions();

// fetch the newest versions first
$versions = $project->fetchVersions(1, VersionOrder::POST_DATE, SortDirection::DESC);

// get the author
$author = $project->getAuthor();

Authors

getAuthor()

XenforoResourceManagerAPI#getAuthor

To get a single author by its numeric id, use getAuthor().

Parameters

• int $id. Required. The numeric id of the author.

$author = $spigotClient->getAuthor(1);

// get data from the wrapper
$id = $author->getData()->getId();
$username = $author->getData()->getUsername();
$resources = $author->getData()->getResourceCount();
$identities = $author->getData()->getIdentities();
$avatarUrl = $author->getData()->getAvatar();
$activity = $author->getData()->getLastActivity();

findAuthor()

XenforoResourceManagerAPI#findAuthor

To find an author by username, use findAuthor().

Parameters

• string $name. Required. The username of the author.

$author = $spigotClient->findAuthor("md_5");

// get data from the wrapper
$id = $author->getData()->getId();
$username = $author->getData()->getUsername();
$resources = $author->getData()->getResourceCount();
$identities = $author->getData()->getIdentities();
$avatarUrl = $author->getData()->getAvatar();
$activity = $author->getData()->getLastActivity();

More information

To request more information about an author from the API, use the methods on the Author wrapper.

// get a specific author (by numeric id)
$author = $spigotClient->getAuthor(1);

// fetch the projects from the API as a PaginatedAuthorProjectList (sends a request)
$projects = $author->fetchProjects();

getAuthorProjects()

XenforoResourceManagerAPI#getResourcesByAuthor

To list all projects for an author (paginated), use getAuthorProjects().

Parameters

• int $id. Required. The numeric id of the author.
• int $page = 1. Optional. Default: 1. The page number to retrieve. Items are paginated at 10 results per page.

// list all projects from Luck
$projects = $spigotClient->getAuthorProjects(100356);
foreach ($projects as $project) {
    echo $project->getData()->getTitle() . PHP_EOL;
}

Resource Updates / Project Versions

getProjectVersions()

XenforoResourceManagerAPI#getResourceUpdates

To fetch paginated updates for a project, use getProjectVersions().

Parameters

• int $id. Required. The numeric id of the project.
• int $page = 1. Optional. Default: 1. The page number to retrieve. Items are paginated at 10 results per page.
• ?VersionOrder $order = null. Optional. Default: null (API default: id). The field to order the results by. From Aternos\SpigotApi\Client\VersionOrder enum.
• ?SortDirection $direction = null. Optional. Default: null (API default: asc). The direction to order the results by. From Aternos\SpigotApi\Client\SortDirection enum.

use Aternos\SpigotApi\Client\SortDirection;
use Aternos\SpigotApi\Client\VersionOrder;

$versions = $spigotClient->getProjectVersions(2);
foreach ($versions as $version) {
    echo $version->getData()->getTitle() . PHP_EOL;
}

// list the newest versions first
$versions = $spigotClient->getProjectVersions(2, 1, VersionOrder::POST_DATE, SortDirection::DESC);

getVersion()

XenforoResourceManagerAPI#getResourceUpdate

To fetch a specific update by its id, use getVersion().

Parameters

• int $id. Required. The numeric id of the version.

$version = $spigotClient->getVersion(352711);
echo $version->getData()->getTitle() . PHP_EOL;
echo $version->getData()->getMessage() . PHP_EOL;

More information

To request more information about a version from the API, use the methods on the Version wrapper.

// get a specific version (by numeric id)
$version = $spigotClient->getVersion(352711);

// get the ID of the project this version belongs to
$projectId = $version->getProjectId();

// fetch the project from the API as a Project wrapper (sends a request)
$project = $version->fetchProject();

Updating the generated code

Update the generated code by installing the openapi generator and running:

openapi-generator-cli generate -c config.yaml

The generated code has to be patched afterwards. The endpoints of the Spigot API are defined as /index.php?action=..., so all other query parameters have to be appended with &, but the generator uses ?. After generating, replace every "?{$query}" with "&{$query}" in src/Api/DefaultApi.php. The unit test testQueryParametersAreAppendedToTheActionParameter fails if this patch is missing.

Tests

This project provides two kinds of automated tests:

Unit tests

Unit tests use fixtures (recorded JSON responses) instead of performing real HTTP requests. Run only unit tests:

vendor/bin/phpunit --testsuite=unit --testdox

Integration tests

Integration tests perform real requests against the live SpigotMC API. Run only integration tests:

vendor/bin/phpunit --testsuite=integration --testdox