aternos/spigot-api

PHP Client for the SpigotMC XenforoResourceManagerAPI. This client is based on the openapi spec.

1.0.0 2025-10-06 15:47 UTC

Requires

• php: ^8.2
• ext-curl: *
• ext-json: *
• ext-mbstring: *
• guzzlehttp/guzzle: ^7.3
• guzzlehttp/psr7: ^1.7 || ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.5
• phpunit/phpunit: ^12.3

MIT

• Aternos GmbH

• php
• api
• plugins
• minecraft
• spigot
• spigotmc

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.2 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 (recommended)
$spigotClient->setUserAgent('aternos/php-spigot-api-example');

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.

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.

$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;
}

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.

$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;
}

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.

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

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

// 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.

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

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)[https://openapi-generator.tech/docs/installation] and running:

openapi-generator-cli generate -c config.yaml

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