https://github.com/aternosorg/php-spigot-api
An API client for the SpigotMC API written in PHP.
https://github.com/aternosorg/php-spigot-api
Last synced: 8 months ago
JSON representation
An API client for the SpigotMC API written in PHP.
- Host: GitHub
- URL: https://github.com/aternosorg/php-spigot-api
- Owner: aternosorg
- Created: 2025-10-06T15:38:03.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-10-06T15:50:11.000Z (8 months ago)
- Last Synced: 2025-10-06T17:02:35.440Z (8 months ago)
- Language: PHP
- Homepage: https://packagist.org/packages/aternos/spigot-api
- Size: 85 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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](https://github.com/SpigotMC/XenforoResourceManagerAPI/) and uses its [OpenAPI specification](https://github.com/SpigotMC/XenforoResourceManagerAPI/blob/master/src/openapi.yaml).
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:
```bash
composer require aternos/spigot-api
```
## Usage
The main entry point for the API is the `SpigotAPIClient` class.
```php
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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#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.
```php
$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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#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.
```php
$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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#getresource)
To get a single project (resource) by its numeric id, use `getProject()`.
**Parameters**
- `int $id`. Required. The numeric id of the project.
```php
// 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.
```php
// 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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#getauthor)
To get a single author by its numeric id, use `getAuthor()`.
**Parameters**
- `int $id`. Required. The numeric id of the author.
```php
$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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#findauthor)
To find an author by username, use `findAuthor()`.
**Parameters**
- `string $name`. Required. The username of the author.
```php
$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.
```php
// get a specific author (by numeric id)
$author = $spigotClient->getAuthor(1);
// get projects as a PaginatedProjectList
$projects = $author->getProjects();
```
### getAuthorProjects()
[XenforoResourceManagerAPI#getResourcesByAuthor](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#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.
```php
// 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](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#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.
```php
$versions = $spigotClient->getProjectVersions(2);
foreach ($versions as $version) {
echo $version->getData()->getTitle() . PHP_EOL;
}
```
### getVersion()
[XenforoResourceManagerAPI#getResourceUpdate](https://github.com/SpigotMC/XenforoResourceManagerAPI?tab=readme-ov-file#getresourceupdate)
To fetch a specific update by its id, use `getVersion()`.
**Parameters**
- `int $id`. Required. The numeric id of the version.
```php
$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.
```php
// 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:
```bash
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:
```bash
vendor/bin/phpunit --testsuite=unit --testdox
```
### Integration tests
Integration tests perform real requests against the live SpigotMC API.
Run only integration tests:
```bash
vendor/bin/phpunit --testsuite=integration --testdox
```