README

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);

// get versions as a PaginatedVersionList
$versions = $project->getVersions();

// get the newest versions first
$versions = $project->getVersions(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);

// get projects as a PaginatedProjectList
$projects = $author->getProjects();

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();

// get the project as a Project wrapper
$project = $version->getProject();

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

aternos / spigot-api

Package info

Security

Statistics

README

Requirements

Installation

Usage

User Agent

Error Handling

Custom HTTP Client or Configuration

Result Lists

listProjects()

listProjectsForCategory()

Projects / Resources

getProject()

More information

Authors

getAuthor()

findAuthor()

More information

getAuthorProjects()

Resource Updates / Project Versions

getProjectVersions()

getVersion()

More information

Updating the generated code

Tests

Unit tests

Integration tests