PHPackages                             colorfield/mastodon-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. colorfield/mastodon-api

ActiveLibrary[HTTP & Networking](/categories/http)

colorfield/mastodon-api
=======================

PHP wrapper for Mastodon API

0.1.5(2y ago)282.9k↓50%5[3 issues](https://github.com/colorfield/mastodon-api-php/issues)[1 PRs](https://github.com/colorfield/mastodon-api-php/pulls)1Apache-2.0PHPPHP >=8.1.0

Since Jul 20Pushed 2y ago5 watchersCompare

[ Source](https://github.com/colorfield/mastodon-api-php)[ Packagist](https://packagist.org/packages/colorfield/mastodon-api)[ Docs](https://github.com/colorfield/mastodon-api-php)[ RSS](/packages/colorfield-mastodon-api/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (9)Versions (7)Used By (1)

Mastodon API PHP
================

[](#mastodon-api-php)

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

[](#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](https://instances.social).
2. Get endpoints from the Mastodon API documentation: [Getting started with the API](https://docs.joinmastodon.org/client/intro/) and [Guidelines and best practices](https://docs.joinmastodon.org/api/guidelines/)

[Some requests](https://docs.joinmastodon.org/client/public/), like public timelines, do not require any authentication.

### Get public data.

[](#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

[](#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](./test_oauth.php), via a local PHP server. It provides the client id, client secret and bearer. See the [Development](#development) section below.

#### Register your application

[](#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](https://docs.joinmastodon.org/api/oauth-scopes/).

#### Get the authorization code

[](#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

[](#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

[](#use-the-mastodon-api)

#### Instantiate the Mastodon API with the configuration

[](#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

[](#user-login)

Login with Mastodon email and password.

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

#### Get

[](#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

[](#post)

Clear notifications

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

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

Development
-----------

[](#development)

### Manual testing tools

[](#manual-testing-tools)

#### OAuth

[](#oauth)

An interactive demo is available.

1. Clone the [GitHub repository](https://github.com/colorfield/mastodon-api-php).
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](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".

[![Authorize your application](documentation/images/mastodon-authorize.png?raw=true "Authorize your application")](documentation/images/mastodon-authorize.png?raw=true)

[![Authorize your application](documentation/images/mastodon-authorization-code.png?raw=true "Authorization code")](documentation/images/mastodon-authorization-code.png?raw=true)

#### Mastodon API

[](#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](http://localhost:8000/test_api.php)

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

6

Last Release

1020d ago

PHP version history (2 changes)v0.1.0PHP >=5.6.0

0.1.1PHP >=8.1.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/e7054894c368f4897b9a2189e5fc3cdc055fff6b2701761b7a8068f121e74dd4?d=identicon)[Colorfield](/maintainers/Colorfield)

---

Top Contributors

[![colorfield](https://avatars.githubusercontent.com/u/525003?v=4)](https://github.com/colorfield "colorfield (69 commits)")

---

Tags

composerguzzlemastodon-apioauthphpphp-wrapperphpapirestmastodon

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/colorfield-mastodon-api/health.svg)

```
[![Health](https://phpackages.com/badges/colorfield-mastodon-api/health.svg)](https://phpackages.com/packages/colorfield-mastodon-api)
```

###  Alternatives

[xeroapi/xero-php-oauth2

Xero official PHP SDK for oAuth2 generated with OpenAPI spec 3

1054.3M14](/packages/xeroapi-xero-php-oauth2)[xendit/xendit-php

Xendit PHP SDK

189730.6k6](/packages/xendit-xendit-php)[onesignal/onesignal-php-api

A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com

34170.2k2](/packages/onesignal-onesignal-php-api)[zenditplatform/zendit-php-sdk

PHP client for Zendit API

1204.3k](/packages/zenditplatform-zendit-php-sdk)[huaweicloud/huaweicloud-sdk-php

Huawei Cloud SDK for PHP

1829.2k2](/packages/huaweicloud-huaweicloud-sdk-php)[ory/hydra-client-php

Documentation for all of Ory Hydra's APIs.

1710.8k](/packages/ory-hydra-client-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)