README

PHP wrapper for the Mastodon API, that includes OAuth helpers. Guzzle based.

This is a plain API wrapper, so it makes it more resilient to changes (new parameters, ...) from the API by letting the developer pass the desired endpoint and parameters.

Quick start

Install it via Composer. Latest version requires PHP 8.1. For previous versions of PHP, use v0.1.0.

composer require colorfield/mastodon-api

1. Get an instance from the instance list.
2. Get endpoints from the Mastodon API documentation: Getting started with the API and Guidelines and best practices

Some requests, like public timelines, do not require any authentication.

Get public data.

Initialize the API.

$name = 'MyMastodonApp';
$instance = 'mastodon.social';
$config = new Colorfield\Mastodon\ConfigurationVO($name, $instance);
$this->api = new MastodonAPI($config);

Request a public endpoint.

$timeline = $this->api->getPublicData('/timelines/public');

which is equivalent to

$timeline = $this->api->get('/timelines/public', [], false);

where the 3rd parameter indicates that we don't require any authentication.

Authenticate with OAuth

This is needed for endpoints that are requiring a token.

To get OAuth credentials, a lightweight client is also available in test_oauth, via a local PHP server. It provides the client id, client secret and bearer. See the Development section below.

Register your application

$name = 'MyMastodonApp';
$instance = 'mastodon.social';
$oAuth = new Colorfield\Mastodon\MastodonOAuth($name, $instance);

The default configuration is limited to the read and write scopes. You can modify it via

$oAuth->config->setScopes(['read', 'write', 'follow', 'push']);

or alternatively use enum

$oAuth->config->setScopes([
    OAuthScope::read->name, 
    OAuthScope::write->name, 
    OAuthScope::follow->name,
    OAuthScope::push->name
]);

Note that this must be done while obtaining the token, so you cannot override this after. More about scopes.

Get the authorization code

1. Get the authorization URL $authorizationUrl = $oAuth->getAuthorizationUrl();
2. Go to this URL, authorize and copy the authorization code.

Get the bearer

1. Store the authorization code in the configuration value object. $oAuth->config->setAuthorizationCode(xxx);

2. Then get the access token. As a side effect, it is store in the Configuration value object. $oAuth->getAccessToken();

Use the Mastodon API

Instantiate the Mastodon API with the configuration

The OAuth credentials should be stored in the Configuration value object for later retrieval.

$name = 'MyMastodonApp';
$instance = 'mastodon.social';
$oAuth = new Colorfield\Mastodon\MastodonOAuth($name, $instance);
$oAuth->config->setClientId('...');
$oAuth->config->setClientSecret('...');
$oAuth->config->setBearer('...');
$mastodonAPI = new Colorfield\Mastodon\MastodonAPI($oAuth->config);

User login

Login with Mastodon email and password.

$oAuth->authenticateUser($email, $password);

Get

Get credentials (assumes by default that authentication is provided).

$credentials = $mastodonAPI->get('/accounts/verify_credentials');

Get followers

$followers = $mastodonAPI->get('/accounts/USER_ID/followers');

Post

Clear notifications

$clearedNotifications = $mastodonAPI->post('/notifications/clear');

@todo complete with delete, put, patch and stream.

Development

Manual testing tools

OAuth

An interactive demo is available.

1. Clone the GitHub repository.
2. cd in the cloned directory
3. Run composer install
4. Run php -S localhost:8000
5. In your browser, go to http://localhost:8000/test_oauth.php
6. You will get the client_id and client_secret, click on the authorization URL link, then confirm the authorization under Mastodon and copy the authorization code.
7. Get the bearer: click on the "Get access token" button.
8. Authenticate with your Mastodon username (email) and password: click on "Login".

Mastodon API

1. Make a copy of .env.local as .env
2. Define the information obtained with OAuth and your Mastodon email and password.
3. In your browser, go to http://localhost:8000/test_api.php