fundevogel/php-mastodon

A small PHP library for interacting with Mastodon's REST API.

0.6.0 2021-09-19 08:01 UTC

Requires

• guzzlehttp/guzzle: ^7.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.14
• phpunit/phpunit: ^8.1

GPL-3.0

• Kinder- und Jugendbuchhandlung Fundevogel
• Martin Folkers

• rest
• api
• oauth
• social
• mastodon

README

A small PHP library for interacting with Mastodon's REST API. Its documentation can be found here.

Note: Before you get started, be sure to create an application (under "Development" in your profile settings) first.

Getting started

Install this package with Composer:

composer require fundevogel/php-mastodon

To get an idea how you could implement this, have a look at these examples:

<?php

require_once('vendor/autoload.php');

use Fundevogel\Mastodon\Api;

# Initialize Api for given instance (defaults to 'mastodon.social')
$api = new Api('freiburg.social');

# Generate access token via ..
# (1) .. OAuth call or ..
$api->accessToken = $api->oauth()->token('cl13nt_1d', 'cl13nt_s3cr3t')['access_token'];

# (2) .. app creation (create an app, get one `access_token` for free!)
$api->accessToken = 'ur-t0t4lly-s3cr3t-p4ssw@rd';

# If you want to obtain an authorization code, and want to know where to get one ..
$url = $api->getAuthURL('cl13nt_1d');

# .. but you might want to provide what you have & use the login helper
$api->logIn();

# This helper takes the authorization code as parameter - however,
# if you provided client key / secret / access token,
# it will attempt to provide whatever access level is possible

# Fetch statuses of given account
foreach ($api->accounts()->statuses('106612343490709443') as $status) {
    echo $status->content();
}

# Note: In case you obtained login-level access, you may omit the ID parameter, which gives back your own account's statuses, like so:
foreach ($api->accounts()->statuses() as $status) {
    echo $status->content();
}

# Fetch followers
foreach ($api->accounts()->followers('106612343490709443') as $follower) {
    echo $follower->displayName();
}

# View your timelines
$timelines = $api->timelines();

# (1) Public timeline
var_dump($timelines->public());

# (2) Home timeline (= accounts you are following)
var_dump($timelines->home());

# Fetch information about your instance
var_dump($api->instance()->get());


# ... enjoy playing with Mastodon's API!

Note: In most cases, using $api->logIn() will be enough. You may then view other people's statuses, etc as well as your own by providing your account ID as parameter as shown above.

.. but I need more docs!

First, have a look at the docs.

Now, all API methods match their URL counterparts:

• mastodon.example/api/v1/accounts/:id becomes $api->accounts()->get($id)
• mastodon.example/api/v1/accounts/:id/statuses becomes $api->accounts()->statuses($id)
• mastodon.example/api/v1/timelines/home becomes $api->timelines()->home()
• mastodon.example/api/v1/statuses/:id becomes $api->statuses()->get($id)

.. same goes for the resulting API entities you get back. For example, the Status entity methods match their array counterparts as found in the docs (only camelcased):

• id may be accessed with $status->id()
• created_at may be accessed with $status->createdAt()
• account may be accessed with $status->account() (which in turn gives an Account entity)

Roadmap

• Add tests
• Add authentication helpers
• Return API entities as individual classes
• Add missing API methods:
  • timelines/streaming
  • notifications/push
  • search
  • admin
• Add missing API entities:
  • admin/account
  • admin/report
• Update empty API entities:
  • error
  • pushsubscription
  • report
  • scheduledstatus

Happy coding!