Download the PHP package vazaha-nl/mastodon-api-client without Composer

mastodon-api-client

A fully typed and complete mastodon API client for PHP.

Features

• 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)

Requirements

• PHP >= 8.1

Installation

Usage

Create the api client

Set base uri / token

Calling API methods

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.

Calls with a single result

All API calls that return a single entity, will return a subclass of \Vazaha\Mastodon\Models\Model.

Calls with multiple results

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.

Pagination

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

Calls with empty or custom result

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:

Error handling

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.

More usage examples

See the examples/ folder.

Laravel support

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:

Testing

Phpstan

All code should pass phpstan analysis on level 9.

Unit tests

Integration tests

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:

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:

Running the integration tests:

Coding style

Coding style is enforced using php-cs-fixer.

Bugs, issues, questions, comments?

Please open an issue on GitHub, send me a mail, or get in touch on Mastodon: https://mastodon.nl/@lhengstmengel.

Author

Lennart Hengstmengel [email protected]

License

This software is open sourced software licensed under the MIT license.