Download the PHP package aternos/spigot-api without Composer

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:

Usage

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

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.

Custom HTTP Client or Configuration

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

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.

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.

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.

More information

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

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.

findAuthor()

XenforoResourceManagerAPI#findAuthor

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

Parameters

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

More information

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

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.

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.

getVersion()

XenforoResourceManagerAPI#getResourceUpdate

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

Parameters

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

More information

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

Updating the generated code

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

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:

Integration tests

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