README.md 6.86 KB
Newer Older
void's avatar
void committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
# MastodonOAuthPHP
PHP Library for Mastodon REST API

## What's in it?

* App creation.
* Full oAuth implementation to authorize your App by users.
* Create and get authorization token, access token, client_id, client_secret and bearer token.
* Authenticate users
* Get user information
* Get user followers and following
* Get user status
* Post status update


## Installation using Composer

```
composer require thecodingcompany/php-mastodon
```

## Questions and example?

Yes, mail me at: vangelier at hotmail dot com
Contact me on #Twitter @digital_human
Contact me on #Mastodon https://mastodon.social/@digitalhuman

## Get started

### Step 1

First step is you need to create a so called App. This app represents your 'service'. With this app you provide services to users or use Mastodon for other reasons.

To create an App is as simple as:

```
<?php
/**
 * Intellectual Property of #Mastodon
 * 
 * @copyright (c) 2017, #Mastodon
 * @author V.A. (Victor) Angelier <victor@thecodingcompany.se>
 * @version 1.0
 * @license http://www.apache.org/licenses/GPL-compatibility.html GPL
 * 
 */
require_once("autoload.php");

$t = new \theCodingCompany\Mastodon();

/**
 * Create a new App and get the client_id and client_secret
 */
$token_info = $t->createApp("MyCoolAppName", "http://www.internet.com");

$serializedData = serialize($token_info);

// save the special tokens to a file, so you don't lose them
file_put_contents('mastodon_creds', $serializedData); // this will save it in the same folder as this file
?>
```

The parameter ```$token_info``` now has your 'client_id' and 'client_secret'. This information is important for the rest of your life ;). Store it in a file, DB or array. You need this everytime you communicate with Mastodon.

### Step 2

Now you (your app) wants to provide services to a user. For this the user needs to authorize your app. Else you can't help him/her. To do this you need to redirect the user, with your tokens to Mastodon and ask for permission so to say. And example:

```
<?php
/**
 * Intellectual Property of #Mastodon
 * 
 * @copyright (c) 2017, #Mastodon
 * @author V.A. (Victor) Angelier <victor@thecodingcompany.se>
 * @version 1.0
 * @license http://www.apache.org/licenses/GPL-compatibility.html GPL
 * 
 */
require_once("autoload.php");

$recoveredData = file_get_contents('mastodon_creds');

// unserializing to get actual array
$recoveredArray = unserialize($recoveredData);

$t = new \theCodingCompany\Mastodon();

/**
 * We now have a client_id and client_secret. Set the domain and provide the library with your App's client_id and secret.
 */
$t->setMastodonDomain("mastodon.social"); // Set the mastodon domain, you can remove this line if you're using mastodon.social as it's the default

$t->setCredentials($recoveredArray); // use the keys from the file we stored in Step 1

/**
* Now that is set we can get the Authorization URL and redirect the user to Mastodon
* After the user approves your App, it will return with an Access Token.
*/
$auth_url = $t->getAuthUrl();
header("Location: {$auth_url}", true);
exit;

```

### Step 3

So you now have 3 tokens. The client_id, client_secret and the users access_token. Now exchange the access token for a bearer token and you are done. Save these tokens!

```
<?php
/**
 * Intellectual Property of #Mastodon
 * 
 * @copyright (c) 2017, #Mastodon
 * @author V.A. (Victor) Angelier <victor@thecodingcompany.se>
 * @version 1.0
 * @license http://www.apache.org/licenses/GPL-compatibility.html GPL
 * 
 */
require_once("autoload.php");

$recoveredData = file_get_contents('mastodon_creds');

// unserializing to get actual array
$recoveredArray = unserialize($recoveredData);

$t = new \theCodingCompany\Mastodon();

/**
 * We now have a client_id and client_secret. Set the domain and provide the library with your App's client_id and secret.
 */
$t->setMastodonDomain("mastodon.social"); // Set the mastodon domain, you can remove this line if you're using mastodon.social as it's the default

$t->setCredentials(recoveredArray); // use the keys from the file we stored in Step 1

$token_info = $t->getAccessToken("7c47d0c636314a1dff21reryyy5edf91884856dc0f78148f848d475136"); //The access token you received in step 2 from the user.

/**
 * The above '$token_info' will now give you a bearer token (If successfull), you also need to store that and keep it safe!
 * 
*/
```

## Step 4

To then post a status, you just do this:

```
require_once("autoload.php");

$t = new \theCodingCompany\Mastodon();

$t->setMastodonDomain(website address); // change this to whatever Mastodon instance you're using, or remove it entirely if you're using mastodon.social (as it's the default)

$t->setCredentials($credentials); // where $credentials are your "client_id", "client_secret" and "bearer" in the form of an array with those exact names (from what you got in the earlier steps)

$t->postStatus('API Test - PLZ ignore <3');
```

## Full code overview options etc

```
<?php
/**
 * Intellectual Property of #Mastodon
 * 
 * @copyright (c) 2017, #Mastodon
 * @author V.A. (Victor) Angelier <victor@thecodingcompany.se>
 * @version 1.0
 * @license http://www.apache.org/licenses/GPL-compatibility.html GPL
 * 
 */
require_once("autoload.php");

$t = new \theCodingCompany\Mastodon();

/**
 * Create a new App and get the client_id and client_secret
 */
$token_info = $t->createApp("MyCoolAppName", "http://www.internet.com");


//Get the authorization url
$auth_url = $t->getAuthUrl();
/*
 * 1) Send the above URL '$auth_url' to the user. The need to authorize your App. 
 * 2) When they authorized your app, they will receive a token. The authorization token.
 * 3) Put the authorization token in the request below to exchange it for a bearer token.
 */

//Request the bearer token
$token_info = $t->getAccessToken("7c47d0c636314a1dff21reryyy5edf91884856dc0f78148f848d475136");

/**
 * The above '$token_info' will now be an array with the info like below. (If successfull)
 * No these are not real, your right.
 * 
    {
        "client_id": "87885c2bf1a9d9845345345318d1eeeb1e48bb676aa747d3216adb96f07",
        "client_secret": "a1284899df5250bd345345f5fb971a5af5c520ca2c3e4ce10c203f81c6",
        "bearer": "77e0daa7f252941ae8343543653454f4de8ca7ae087caec4ba85a363d5e08de0d"
    }
 */

/**
 * Authenticate a user by username and password and receive the bearer token
 */
$bearer_token = $t->authUser("vangelier@hotmail.com", "MySecretP@ssW0rd");

/**
 * Get the userinfo by authentication
 */

$user_info = $t->getUser("vangelier@hotmail.com", "MySecretP@ssW0rd");

/**
 * Get user followers / following
 */
$followers = $t->authenticate("vangelier@hotmail.com", "MySecretP@ssW0rd")
                ->getFollowers();

/**
 * Get user statusses
 */
$statusses = $t->authenticate("vangelier@hotmail.com", "MySecretP@ssW0rd")
                ->getStatuses();


/**
* Post status update
*/

$status = $t->authenticate("vangelier@hotmail.com", "MySecretP@ssW0rd")
            ->postStatus("Text status update");

```