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

mastodon-api-client

A fully typed and feature 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.

Testing

There are some basic integration tests available as well. If you want to run these, you will need a local mastodon instance at http://mastodon.local. See https://docs.joinmastodon.org/dev/setup/#vagrant for instructions.

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.