A fully typed and complete mastodon API client for PHP.
- complete: every documented api method and entity has been implemented
- fully typed: every function, argument, property and result is typed, using generics where applicable
- documented: every api entity, method and argument is documented using docblocks, and contain a link to the relevant page at https://docs.joinmastodon.org
- tested: the code is covered by unit and integration tests, and passes phpstan analysis on the highest level
- up to date: classes are auto generated based on the Mastodon markup documentation (in absence of a good openapi spec)
- PHP >= 8.1
composer require vazaha-nl/mastodon-api-client
// using the factory
$factory = new \Vazaha\Mastodon\Factories\ApiClientFactory();
$client = $factory->build();
// instantiate directly, with the httpclient implementation of your choice
$client = new \Vazaha\Mastodon\ApiClient(new \GuzzleHttp\Client());// set base uri (required)
$client->setBaseUri('https://instance.example');
// manually set access token
$client->setAccessToken('token...');Every method is exposed through the $client->methods() proxy. It is highly recommended to use a LSP enabled IDE.
The methods are named and organized exactly like in the official documentation, with documentation in docblocks.
All API calls that return a single entity, will return a subclass of \Vazaha\Mastodon\Models\Model.
try {
// get an account by id
// returns instance of \Vazaha\Mastodon\Models\AccountModel
$account = $client->methods()->accounts()->get('the account id');
} catch (NotFoundException $e) {
// no account exists with this id
$error = $e->getError(); // instance of \Vazaha\Mastodon\Models\ErrorModel
// ..
}
print 'Found account: ' . $account->display_name . \PHP_EOL;Calls that return a list of entities, will return a subclass of \Vazaha\Mastodon\Results\Result. This class is a subclass of \Illuminate\Support\Collection which can be accessed as an array. The collection will contain the result model(s) (implementations of \Vazaha\Interfaces\ModelInterface). The exact subclass will be type hinted and thus known to your IDE.
// get the followers of account with specified id.
// returns instance of \Vazaha\Mastodon\Results\AccountResult
$followers = $client->methods()->accounts()->followers($account->id);
foreach ($followers as $follower) {
// contains \Vazaha\Mastodon\Models\AccountModel instances
print 'Follower : ' . $follower->display_name . \PHP_EOL;
}Most API calls with multiple results have a hard limit on the amount of results returned. To get the next/previous page of a result, use the getNextPage() / getPreviousPage() methods. This is done by parsing the Link http header. See for background: https://docs.joinmastodon.org/api/guidelines/#pagination
while ($followers = $followers->getNextPage()) {
// ...
}Some calls do not return a model or array of models. Some have an empty result, some have a custom result, like an array of strings or custom hashes, or plain text. Refer to the documentation for details. In all those cases the Result will be an instance of \Vazaha\Mastodon\Results\EmptyOrUnknownResult, and the collection will be empty. Retrieve the response using one of the following methods:
// get the decoded json content, if available
$decoded = $result->getDecodedBody();
// get the undecoded response body
$body = $result->getBody();
// get the entire Http Response object
$response = $result->getHttpResponse();In case of any client (4xx) http errors, custom exceptions (subclasses of \Vazaha\Mastodon\Exceptions\ApiErrorException) will be thrown, containing an Error object. There is a specific exception class for every status code.
See the examples/ folder.
The ServiceProvider class, which will be automatically detected, provides very basic Laravel support, enabling dependency injection of the ApiClient class. For example in a controller:
public function myControllerFunction(Request $request, ApiClient $client)
{
/** @var \App\Models\User $user */
$user = $request->user();
$client->setBaseUri('https://instance.example')
->setAccessToken($user->mastodon_access_token);
// ...
}All code should pass phpstan analysis on level 9.
composer analyse
composer test
These tests run on an actual (local!) mastodon instance. Do not use a live server for this.
The easiest way to set up a local mastodon server is using Vagrant. See https://docs.joinmastodon.org/dev/setup/#vagrant for instructions. It is assumed that this server runs at http://mastodon.local. If you have a different setup, set the domain in tests/Integration/.env:
BASE_URI=http://your-local-mastodon-domain.tld
To run the tests, you will need a valid access token for the admin user. To get one, run the tests/Integration/get_admin_access_token.php script and follow the prompts. It will create an app and take you through the oauth flow. The credentials will be stored in tests/Integration/.env.
Apart from the admin token, you will also need a local test mastodon user user1. You can create one using the toot util. If you're using vagrant:
cd <path of mastodon repository>
# bring the server up, if needed:
vagrant up
# ssh into your vagrant machine
vagrant ssh
cd /vagrant
# create a confirmed user
bin/tootctl accounts create user1 [email protected] --confirmed
# approve the user
bin/tootctl accounts modify user1 --approve
Running the integration tests:
composer integration-test
Coding style is enforced using php-cs-fixer.
# check only, no modifications will be made
composer check-style
# fix all files if possible
composer fix-style
Please open an issue on GitHub, send me a mail, or get in touch on Mastodon: https://mastodon.nl/@lhengstmengel.
Lennart Hengstmengel [email protected]
This software is open sourced software licensed under the MIT license.