Aternos/php-hangar-api

An API client for the Hangar API written in PHP.

This client is a combination of code generated by OpenAPI Generator from the Hangar OpenAPI specification and some wrappers around it to improve the usability.

The generated code can be found in src/Api and src/Model. It is recommended to use the wrappers in src/Client instead. The wrappers provide methods to fetch related data from the API, the data returned by the API is available through getData().

Requirements

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

Installation

Install the package via composer:

composer require aternos/hangar-api

Usage

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

<?php
use Aternos\HangarApi\Client\HangarAPIClient;

$hangarClient = new HangarAPIClient();

// set a user agent identifying your application (recommended)
$hangarClient->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-hangar-api/5.1.1. A user agent set with setUserAgent() replaces it.

Authentication

Most endpoints are public. Some endpoints (e.g. the daily stats of projects and versions or editing pages) require an API key, which you can create in your account settings. If an API key is set, it is used for all requests. The client exchanges it for a JWT automatically.

$hangarClient->setApiKey("your-api-key");

You can check whether the API key has certain permissions, optionally for a specific project:

use Aternos\HangarApi\Model\NamedPermission;

$canEditPages = $hangarClient->hasPermission(NamedPermission::EDIT_PAGE, "mclogs");

Error Handling

All methods that send a request throw an Aternos\HangarApi\ApiException if the request fails. The exception code is the HTTP status code of the response. It is also thrown if a required permission is missing, e.g. when requesting daily stats without an API key.

use Aternos\HangarApi\ApiException;

try {
    $project = $hangarClient->getProject("does-not-exist");
} catch (ApiException $e) {
    echo $e->getCode() . PHP_EOL; // e.g. 404
    var_dump($e->getResponseBody());
}

Custom HTTP Client or Configuration

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

use Aternos\HangarApi\Configuration;
use GuzzleHttp\Client;

$hangarClient = new HangarAPIClient(
    configuration: new Configuration(),
    httpClient: new Client(["timeout" => 10]),
);
// or
$hangarClient->setHttpClient(new Client(["timeout" => 10]));

Result Lists

Most methods return a paginated result list which contains a list of results on the current page and methods to navigate to the next and previous page. The result list implements Iterator, ArrayAccess and Countable so you can use it like an array. It also has a getResults() method which returns the underlying array of results.

$projects = $hangarClient->getProjects();

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

if ($projects->hasNextPage()) {
    $projects = $projects->getNextPage();
}

// fetch all results from this and all following pages (one request per page)
$allProjects = $projects->getResultsFromFollowingPages();

Projects

Searching for Projects

You can search for a query, apply filters, change the sort order and set the page size. All options are optional and can be combined.

use Aternos\HangarApi\Client\Options\ProjectSearch\ProjectSearchOptions;
use Aternos\HangarApi\Client\Options\ProjectSearch\ProjectSortField;
use Aternos\HangarApi\Client\Options\ProjectSearch\ProjectSortOrder;
use Aternos\HangarApi\Model\Category;
use Aternos\HangarApi\Model\Platform;

$options = new ProjectSearchOptions()
    ->setQuery("mclogs")
    ->setCategory(Category::ADMIN_TOOLS)
    ->setPlatform(Platform::PAPER)
    ->setSortField(ProjectSortField::DOWNLOADS)
    ->setSortOrder(ProjectSortOrder::DESC)
    ->setLimit(10);

$projects = $hangarClient->getProjects($options);

Fetching Projects

// get a project by its slug or id
$project = $hangarClient->getProject("mclogs");
echo $project->getData()->getName() . ": " . $project->getData()->getStats()->getDownloads() . " downloads" . PHP_EOL;

// get the project a file belongs to by the SHA-256 hash of the file
$project = $hangarClient->getProjectByVersionHash(hash_file("sha256", "/path/to/plugin.jar"));

Additional Project Data

The Project wrapper provides methods to fetch related data:

$project = $hangarClient->getProject("mclogs");

// versions of the project (paginated), optionally filtered by channel and platform
$versions = $project->getVersions();
$versions = $project->getVersions("Release", Platform::PAPER);

// a specific version by its name
$version = $project->getVersion("3.3.4");

// the owner of the project
$owner = $project->getOwner();

// members, stargazers and watchers of the project (paginated)
$members = $project->getMembers();
$stargazers = $project->getStarGazers();
$watchers = $project->getWatchers();

// pages of the project
$mainPage = $project->getMainPage();
$page = $project->getPage("config");

The daily stats of a project require an API key of a member of the project:

// stats since the project was created, or for a specific period
$stats = $project->getDailyStats();
$stats = $project->getDailyStats(new DateTime("2026-01-01"), new DateTime("2026-02-01"));

foreach ($stats as $date => $dayStats) {
    echo $date . ": " . $dayStats->getDownloads() . " downloads, " . $dayStats->getViews() . " views" . PHP_EOL;
}

Compact Projects

Some methods, e.g. the projects a user has starred, return CompactProject objects. They contain less data, but provide the same methods as Project. You can fetch the full project:

foreach ($hangarClient->getUser("Aternos")->getStarredProjects() as $compactProject) {
    $project = $compactProject->getProject();
}

Versions

use Aternos\HangarApi\Client\Options\VersionSearch\VersionSearchOptions;

// get the versions of a project (paginated), optionally filtered by channel and platform
$options = new VersionSearchOptions("mclogs")
    ->setChannel("Release")
    ->setPlatform(Platform::PAPER);
$versions = $hangarClient->getProjectVersions("mclogs", $options);

// get a version of a project by its name or id
$version = $hangarClient->getVersion("mclogs", "3.3.4");

// get a version by its id
$version = $hangarClient->getVersionById(30673);

// get the name of the latest release version or of the latest version in a channel
$latestRelease = $hangarClient->getLatestReleaseVersion("mclogs");
$latestVersion = $hangarClient->getLatestVersion("mclogs", "Release");

// get the project of a version
$project = $version->getProject();

The daily stats of a version require an API key:

$stats = $version->getDailyStats();

foreach ($stats as $date => $dayStats) {
    echo $date . ": " . $dayStats->getTotalDownloads() . " downloads" . PHP_EOL;
}

Users

use Aternos\HangarApi\Client\Options\UserSearch\StaffSortField;
use Aternos\HangarApi\Client\Options\UserSearch\UserSearchOptions;
use Aternos\HangarApi\Client\Options\UserSearch\UserSortField;

// get a user by name
$user = $hangarClient->getUser("Aternos");
echo $user->getData()->getName() . ": " . $user->getData()->getProjectCount() . " projects" . PHP_EOL;

// search for users (paginated)
$users = $hangarClient->getUsers(new UserSearchOptions()->setQuery("aternos")->setSort(UserSortField::NAME));

// get the staff and the authors (paginated)
$staff = $hangarClient->getStaff(sort: StaffSortField::ROLES);
$authors = $hangarClient->getAuthors("aternos");

// get the projects of a user (paginated)
$projects = $user->getProjects();

// get the projects a user has starred or is watching (paginated)
$starredProjects = $user->getStarredProjects();
$watchedProjects = $user->getWatchedProjects();

// get the projects a user has pinned on their profile
$pinnedProjects = $user->getPinnedProjects();

Project Pages

// get the main page of a project
$page = $hangarClient->getProjectMainPage("mclogs");
echo $page->getContent();

// get another page by its path
$page = $hangarClient->getProjectPage("mclogs", "config");

Editing pages requires an API key with the edit_page permission for the project:

$page->setContent("# New content");
$page->save();

// or without loading the page first
$hangarClient->editProjectPage("mclogs", "config", "# New content");
$hangarClient->editProjectMainPage("mclogs", "# New content");

Development

Updating the Generated Code

Install the OpenAPI Generator and run:

openapi-generator-cli generate -c config.yaml