|
1 | | -# ZendService\Twitter component |
| 1 | +# zendservice-twitter |
2 | 2 |
|
3 | | -Master: [](http://travis-ci.org/zendframework/ZendService_Twitter) |
| 3 | +[](https://secure.travis-ci.org/zendframework/ZendService_Twitter) |
| 4 | +[](https://coveralls.io/github/zendframework/ZendService_Twitter?branch=master) |
4 | 5 |
|
5 | | -You can install using Composer: |
| 6 | +Provides an object oriented PHP wrapper for the [Twitter API](https://developer.twitter.com/en/docs). |
| 7 | + |
| 8 | +## Installation |
| 9 | + |
| 10 | +Run the following to install this library: |
6 | 11 |
|
7 | 12 | ```bash |
8 | 13 | $ composer require zendframework/zendservice-twitter |
9 | 14 | ``` |
10 | 15 |
|
11 | | -At that point, follow the instructions in the documentation folder for actual |
12 | | -usage of the component. (Documentation is forthcoming.) |
| 16 | +## Usage |
| 17 | + |
| 18 | +Instantiate the `Twitter` class by providing your Twitter consumer key and |
| 19 | +secret, as well as the access token and secret: |
| 20 | + |
| 21 | +```php |
| 22 | +use ZendService\Twitter\Twitter; |
| 23 | + |
| 24 | +$twitter = new Twitter([ |
| 25 | + 'access_token' => [ |
| 26 | + 'token' => '<token value>', |
| 27 | + 'secret' => '<token secret value>', |
| 28 | + ], |
| 29 | + 'oauth_options' => [ |
| 30 | + 'consumerKey' => '<consumer key value>', |
| 31 | + 'consumerSecret' => '<consumer secret value>', |
| 32 | + ], |
| 33 | +]); |
| 34 | +``` |
| 35 | + |
| 36 | +Once you have done that, you may start making calls to the API. This can be done |
| 37 | +in one of three ways: |
| 38 | + |
| 39 | +- Using direct method calls on the `Twitter` class. A full list is provided |
| 40 | + below. |
| 41 | +- Using the "proxy" functionality. In these cases, you will provide the first |
| 42 | + path element of the API, and then call a method on it: |
| 43 | + `$twitter->statuses->update($message)`. |
| 44 | +- Using the `get()` or `post()` methods. |
| 45 | + |
| 46 | +## Available methods |
| 47 | + |
| 48 | +- `accountVerifyCredentials() : Response` |
| 49 | +- `applicationRateLimitStatus() : Response` |
| 50 | +- `blocksCreate($id) : Response` |
| 51 | +- `blocksDestroy($id) : Response` |
| 52 | +- `blocksIds(int $cursor = -1) : Response` |
| 53 | +- `blocksList(int $cursor = -1) : Response` |
| 54 | +- `directMessagesDestroy($id) : Response` |
| 55 | +- `directMessagesMessages(array $options = []) : Response` |
| 56 | +- `directMessagesNew($user, string $text, array $extraParams = []) : Response` |
| 57 | +- `directMessagesEventsNew($user, string $text, array $extraParams = []) : Response` |
| 58 | +- `directMessagesSent(array $options = []) : Response` |
| 59 | +- `favoritesCreate($id) : Response` |
| 60 | +- `favoritesDestroy($id) : Response` |
| 61 | +- `favoritesList(array $options = []) : Response` |
| 62 | +- `followersIds($id, array $params = []) : Response` |
| 63 | +- `friendsIds($id, array $params = []) : Response` |
| 64 | +- `friendshipsCreate($id, array $params = []) : Response` |
| 65 | +- `friendshipsLookup($id, array $params = []) : Response` |
| 66 | +- `friendshipsDestroy($id) : Response` |
| 67 | +- `listsMembers($listIdOrSlug, array $params = []) : Response` |
| 68 | +- `listsMemberships($id, array $params = []) : Response` |
| 69 | +- `listsSubscribers($id, array $params = []) : Response` |
| 70 | +- `searchTweets(string $query, array $options = []) : Response` |
| 71 | +- `statusesDestroy($id) : Response` |
| 72 | +- `statusesHomeTimeline(array $options = []) : Response` |
| 73 | +- `statusesMentionsTimeline(array $options = []) : Response` |
| 74 | +- `statusesSample() : Response` |
| 75 | +- `statusesShow($id, array $options = []) : Response` |
| 76 | +- `statusesUpdate(string $status, $inReplyToStatusId = null, $extraAttributes = []) : Response` |
| 77 | +- `statusesUserTimeline(array $options = []) : Response` |
| 78 | +- `usersLookup($id, array $params = []) : Response` |
| 79 | +- `usersSearch(string $query, array $options = []) : Response` |
| 80 | +- `usersShow($id) : Response` |
| 81 | + |
| 82 | +## Proxy Properties |
| 83 | + |
| 84 | +The following proxy properties are allowed: |
| 85 | + |
| 86 | +- account |
| 87 | +- application |
| 88 | +- blocks |
| 89 | +- directmessages |
| 90 | +- favorites |
| 91 | +- followers |
| 92 | +- friends |
| 93 | +- friendships |
| 94 | +- lists |
| 95 | +- search |
| 96 | +- statuses |
| 97 | +- users |
| 98 | + |
| 99 | +In each case, you can identify available methods for the proxy by comparing the |
| 100 | +proxy name to the above list of methods. As an example, the `users` proxy allows |
| 101 | +the following: |
| 102 | + |
| 103 | +```php |
| 104 | +$twitter->users->lookup($id, array $params = []); |
| 105 | +$twitter->users->search(string $query, array $options = []); |
| 106 | +$twitter->users->show($id); |
| 107 | +``` |
| 108 | + |
| 109 | +## Direct access |
| 110 | + |
| 111 | +The Twitter API has dozens of endpoints, some more popular and/or useful than |
| 112 | +others. As such, we are only providing a subset of what is available. |
| 113 | + |
| 114 | +However, we allow you to access any endpoint via either the `get()` or `post()` |
| 115 | +methods, which have the following signatures: |
| 116 | + |
| 117 | +```php |
| 118 | +public function get(string $path, array $query = []) : Response; |
| 119 | +public function post(string $path, $data = null) : Response; |
| 120 | +``` |
| 121 | + |
| 122 | +In each case, the `$path` is the API endpoint as detailed in the Twitter API |
| 123 | +documentation, minus any `.json` suffix, and the method name corresponds to |
| 124 | +whether the request happens via HTTP GET or POST. |
| 125 | + |
| 126 | +For HTTP GET requests, the `$query` argument provides any query string |
| 127 | +parameters you want to pass for that endpoint. As an example, if you were |
| 128 | +requesting `statuses/home_timeline`, you might pass `count` or `since_id`. |
| 129 | + |
| 130 | +For HTTP POST requests, the `$data` argument can be one of: |
| 131 | + |
| 132 | +- An associative array of data. |
| 133 | +- A serializable object of data. |
| 134 | +- A string representing the raw payload. |
| 135 | + |
| 136 | +The data to provide will vary based on the endpoint. |
| 137 | + |
| 138 | +## Media uploads |
| 139 | + |
| 140 | +Since version 3.0, we have supported media uploads via the classes |
| 141 | +`ZendService\Twitter\Media`, `Image`, and `Video`. In each case, you will |
| 142 | +instantiate the appropriate class with the local filesystem path of the image to |
| 143 | +upload and the media type, followed by calling `upload()` with a properly |
| 144 | +configured HTTP client. The response will contain a `media_id` property, which |
| 145 | +you can then provide via the `media_ids` parameter when posting a status: |
| 146 | + |
| 147 | + |
| 148 | +```php |
| 149 | +$image = new Image('data/logo.png', 'image/png'); |
| 150 | +$response = $image->upload($twitter->getHttpClient()); |
| 151 | + |
| 152 | +$twitter->statusUpdate( |
| 153 | + 'A post with an image', |
| 154 | + null, |
| 155 | + ['media_ids' => [$response->media_id]] |
| 156 | +); |
| 157 | +``` |
| 158 | + |
| 159 | +When providing media for direct messages, you must provide additional flags to |
| 160 | +the media class's constructor: |
| 161 | + |
| 162 | +- A flag indicating it is for a direct message |
| 163 | +- A flag indicating whether or not the uploaded media may be shared/re-used in |
| 164 | + other direct messages. |
| 165 | + |
| 166 | +```php |
| 167 | +$image = new Image( |
| 168 | + 'data/logo.png', |
| 169 | + 'image/png', |
| 170 | + $forDirectMessage = true, |
| 171 | + $shared = false |
| 172 | +); |
| 173 | +$upload = $image->upload($twitter->getHttpClient()); |
| 174 | +``` |
| 175 | + |
| 176 | +Unlike non-DM media uploads, the identifier will be in the `id_str` parameter of |
| 177 | +the returned upload instance; use that as a `media_id` in your DM: |
| 178 | + |
| 179 | +```php |
| 180 | +$twitter->directmessagesEventsNew( |
| 181 | + $user, |
| 182 | + $message, |
| 183 | + ['media_id' => $upload->id_str] |
| 184 | +); |
| 185 | +``` |
| 186 | + |
| 187 | +Note: direct messages only support a single attachment. |
| 188 | + |
| 189 | +## Rate limiting |
| 190 | + |
| 191 | +As of version 3.0, we now provide introspection of Twitter's rate limit headers, |
| 192 | +allowing you to act on them: |
| 193 | + |
| 194 | +```php |
| 195 | +$response = $twitter->statusUpdate('A post'); |
| 196 | +$rateLimit = $response->getRateLimit(); |
| 197 | +if ($rateLimit->remaining === 0) { |
| 198 | + // Time to back off! |
| 199 | + sleep($rateLimit->reset); // seconds left until reset |
| 200 | +} |
| 201 | +``` |
0 commit comments