{"id":15283914,"url":"https://github.com/colorfield/mastodon-api-php","last_synced_at":"2025-04-12T23:20:25.186Z","repository":{"id":56956755,"uuid":"89097546","full_name":"colorfield/mastodon-api-php","owner":"colorfield","description":"PHP wrapper for the Mastodon API.","archived":false,"fork":false,"pushed_at":"2023-08-09T19:40:01.000Z","size":189,"stargazers_count":22,"open_issues_count":5,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-04-13T21:17:46.868Z","etag":null,"topics":["composer","guzzle","mastodon-api","oauth","php","php-wrapper"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colorfield.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-04-22T20:34:50.000Z","updated_at":"2024-02-05T21:57:21.000Z","dependencies_parsed_at":"2023-09-21T20:00:41.177Z","dependency_job_id":"d4e04f73-4d21-45e4-8869-d1b0cb2a8253","html_url":"https://github.com/colorfield/mastodon-api-php","commit_stats":{"total_commits":69,"total_committers":2,"mean_commits":34.5,"dds":"0.42028985507246375","last_synced_commit":"a4c62d15e78f762939f0eb4a6720b317700d96c5"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colorfield%2Fmastodon-api-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colorfield%2Fmastodon-api-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colorfield%2Fmastodon-api-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colorfield%2Fmastodon-api-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colorfield","download_url":"https://codeload.github.com/colorfield/mastodon-api-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643888,"owners_count":21138523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer","guzzle","mastodon-api","oauth","php","php-wrapper"],"created_at":"2024-09-30T14:48:12.239Z","updated_at":"2025-04-12T23:20:25.159Z","avatar_url":"https://github.com/colorfield.png","language":"PHP","readme":"# Mastodon API PHP\n\nPHP wrapper for the Mastodon API, that includes OAuth helpers. Guzzle based.\n\nThis is a plain API wrapper, so it makes it more resilient to changes (new parameters, ...) from the API\nby letting the developer pass the desired endpoint and parameters.\n\n## Quick start\n\nInstall it via Composer.\nLatest version requires PHP 8.1. For previous versions of PHP, use `v0.1.0`.\n\n```bash\ncomposer require colorfield/mastodon-api\n```\n\n1. Get an instance from the [instance list](https://instances.social).\n2. 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/)\n\n[Some requests](https://docs.joinmastodon.org/client/public/), like public timelines, do not require any authentication.\n\n### Get public data.\n\nInitialize the API.\n\n```php\n$name = 'MyMastodonApp';\n$instance = 'mastodon.social';\n$config = new Colorfield\\Mastodon\\ConfigurationVO($name, $instance);\n$this-\u003eapi = new MastodonAPI($config);\n```\n\nRequest a public endpoint.\n\n```php\n$timeline = $this-\u003eapi-\u003egetPublicData('/timelines/public');\n```\n\nwhich is equivalent to\n\n```php\n$timeline = $this-\u003eapi-\u003eget('/timelines/public', [], false);\n```\n\nwhere the 3rd parameter indicates that we don't require any authentication.\n\n### Authenticate with OAuth\n\nThis is needed for endpoints that are requiring a token.\n\nTo get OAuth credentials, a lightweight client is also available in [test_oauth](./test_oauth.php), \nvia a local PHP server. It provides the client id, client secret and bearer.\nSee the [Development](#development) section below.\n\n#### Register your application\n\n```php\n$name = 'MyMastodonApp';\n$instance = 'mastodon.social';\n$oAuth = new Colorfield\\Mastodon\\MastodonOAuth($name, $instance);\n```\n\nThe default configuration is limited to the `read` and `write` scopes.\nYou can modify it via\n\n```php\n$oAuth-\u003econfig-\u003esetScopes(['read', 'write', 'follow', 'push']);\n```\n\nor alternatively use enum\n\n```php\n$oAuth-\u003econfig-\u003esetScopes([\n    OAuthScope::read-\u003ename, \n    OAuthScope::write-\u003ename, \n    OAuthScope::follow-\u003ename,\n    OAuthScope::push-\u003ename\n]);\n```\n\nNote that this must be done while obtaining the token, so you cannot override this after.\n[More about scopes](https://docs.joinmastodon.org/api/oauth-scopes/).\n\n#### Get the authorization code\n\n1. Get the authorization URL `$authorizationUrl = $oAuth-\u003egetAuthorizationUrl();`\n2. Go to this URL, authorize and copy the authorization code.\n\n#### Get the bearer\n\n1. Store the authorization code in the configuration value object.\n`$oAuth-\u003econfig-\u003esetAuthorizationCode(xxx);`\n\n2. Then get the access token. As a side effect, it is store in the Configuration value object.\n`$oAuth-\u003egetAccessToken();`\n\n### Use the Mastodon API\n\n#### Instantiate the Mastodon API with the configuration\n\nThe OAuth credentials should be stored in the Configuration value object for later retrieval.\n\n```php\n$name = 'MyMastodonApp';\n$instance = 'mastodon.social';\n$oAuth = new Colorfield\\Mastodon\\MastodonOAuth($name, $instance);\n$oAuth-\u003econfig-\u003esetClientId('...');\n$oAuth-\u003econfig-\u003esetClientSecret('...');\n$oAuth-\u003econfig-\u003esetBearer('...');\n$mastodonAPI = new Colorfield\\Mastodon\\MastodonAPI($oAuth-\u003econfig);\n```\n\n#### User login\n\nLogin with Mastodon email and password.\n\n```php\n$oAuth-\u003eauthenticateUser($email, $password);\n```\n\n#### Get\n\nGet credentials (assumes by default that authentication is provided).\n\n```php\n$credentials = $mastodonAPI-\u003eget('/accounts/verify_credentials');\n```\n\nGet followers\n\n```php\n$followers = $mastodonAPI-\u003eget('/accounts/USER_ID/followers');\n```\n\n#### Post\n\nClear notifications\n\n```php\n$clearedNotifications = $mastodonAPI-\u003epost('/notifications/clear');\n```\n\n@todo complete with delete, put, patch and stream.\n\n## Development\n\n### Manual testing tools\n\n#### OAuth\n\nAn interactive demo is available.\n\n1. Clone the [GitHub repository](https://github.com/colorfield/mastodon-api-php).\n2. cd in the cloned directory\n2. Run `composer install`\n3. Run `php -S localhost:8000`\n4. In your browser, go to http://localhost:8000/test_oauth.php\n5. 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.\n6. Get the bearer: click on the \"Get access token\" button.\n7. Authenticate with your Mastodon username (email) and password: click on \"Login\".\n\n![Authorize your application](documentation/images/mastodon-authorize.png?raw=true \"Authorize your application\")\n\n![Authorize your application](documentation/images/mastodon-authorization-code.png?raw=true \"Authorization code\")\n\n#### Mastodon API\n\n1. Make a copy of `.env.local` as `.env`\n2. Define the information obtained with OAuth and your Mastodon email and password.\n3. In your browser, go to http://localhost:8000/test_api.php\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolorfield%2Fmastodon-api-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolorfield%2Fmastodon-api-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolorfield%2Fmastodon-api-php/lists"}