From 2f9be3d9366a451e287385cb479954b5b1b17272 Mon Sep 17 00:00:00 2001 From: Matthew Weier O'Phinney Date: Tue, 21 Nov 2017 15:22:47 -0600 Subject: [PATCH] Synced support documentation and provided initial usage documentation - Updated the Travis configuration to match templates. - Updated the ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and SUPPORT to match the maintainers templates. - Added usage documentation to the README. --- .travis.yml | 20 ++-- README.md | 199 +++++++++++++++++++++++++++++++++- docs/ISSUE_TEMPLATE.md | 8 ++ docs/PULL_REQUEST_TEMPLATE.md | 32 ++++-- docs/SUPPORT.md | 4 +- 5 files changed, 235 insertions(+), 28 deletions(-) diff --git a/.travis.yml b/.travis.yml index 4225b01..0ee9fae 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,11 +5,11 @@ language: php cache: directories: - $HOME/.composer/cache - - vendor env: global: - COMPOSER_ARGS="--no-interaction" + - COVERAGE_DEPS="satooshi/php-coveralls" matrix: include: @@ -19,7 +19,8 @@ matrix: - php: 7.1 env: - DEPS=locked - - CHECK_CS=true + - CS_CHECK=true + - TEST_COVERAGE=true - php: 7.1 env: - DEPS=latest @@ -32,22 +33,23 @@ matrix: - php: 7.2 env: - DEPS=latest - allow_failures: - - php: 7.2 before_install: - - if [[ $TRAVIS_PHP_VERSION =~ ^7.1 ]]; then phpenv config-rm xdebug.ini || return 0 ; fi - - travis_retry composer self-update + - if [[ $TEST_COVERAGE != 'true' ]]; then phpenv config-rm xdebug.ini || return 0 ; fi install: - - travis_retry composer install $COMPOSER_ARGS --ignore-platform-reqs + - travis_retry composer install $COMPOSER_ARGS - if [[ $DEPS == 'latest' ]]; then travis_retry composer update $COMPOSER_ARGS ; fi - if [[ $DEPS == 'lowest' ]]; then travis_retry composer update --prefer-lowest --prefer-stable $COMPOSER_ARGS ; fi + - if [[ $TEST_COVERAGE == 'true' ]]; then travis_retry composer require --dev $COMPOSER_ARGS $COVERAGE_DEPS ; fi - stty cols 120 && composer show script: - - composer test - - if [[ $CHECK_CS == 'true' ]]; then composer cs-check ; fi + - if [[ $TEST_COVERAGE == 'true' ]]; then composer test-coverage ; else composer test ; fi + - if [[ $CS_CHECK == 'true' ]]; then composer cs-check ; fi + +after_script: + - if [[ $TEST_COVERAGE == 'true' ]]; then composer upload-coverage ; fi notifications: email: false diff --git a/README.md b/README.md index 2e7cf16..3c2b3f9 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,201 @@ -# ZendService\Twitter component +# zendservice-twitter -Master: [![Build Status](https://secure.travis-ci.org/zendframework/ZendService_Twitter.png?branch=master)](http://travis-ci.org/zendframework/ZendService_Twitter) +[![Build Status](https://secure.travis-ci.org/zendframework/ZendService_Twitter.svg?branch=master)](https://secure.travis-ci.org/zendframework/ZendService_Twitter) +[![Coverage Status](https://coveralls.io/repos/github/zendframework/ZendService_Twitter/badge.svg?branch=master)](https://coveralls.io/github/zendframework/ZendService_Twitter?branch=master) -You can install using Composer: +Provides an object oriented PHP wrapper for the [Twitter API](https://developer.twitter.com/en/docs). + +## Installation + +Run the following to install this library: ```bash $ composer require zendframework/zendservice-twitter ``` -At that point, follow the instructions in the documentation folder for actual -usage of the component. (Documentation is forthcoming.) +## Usage + +Instantiate the `Twitter` class by providing your Twitter consumer key and +secret, as well as the access token and secret: + +```php +use ZendService\Twitter\Twitter; + +$twitter = new Twitter([ + 'access_token' => [ + 'token' => '', + 'secret' => '', + ], + 'oauth_options' => [ + 'consumerKey' => '', + 'consumerSecret' => '', + ], +]); +``` + +Once you have done that, you may start making calls to the API. This can be done +in one of three ways: + +- Using direct method calls on the `Twitter` class. A full list is provided + below. +- Using the "proxy" functionality. In these cases, you will provide the first + path element of the API, and then call a method on it: + `$twitter->statuses->update($message)`. +- Using the `get()` or `post()` methods. + +## Available methods + +- `accountVerifyCredentials() : Response` +- `applicationRateLimitStatus() : Response` +- `blocksCreate($id) : Response` +- `blocksDestroy($id) : Response` +- `blocksIds(int $cursor = -1) : Response` +- `blocksList(int $cursor = -1) : Response` +- `directMessagesDestroy($id) : Response` +- `directMessagesMessages(array $options = []) : Response` +- `directMessagesNew($user, string $text, array $extraParams = []) : Response` +- `directMessagesEventsNew($user, string $text, array $extraParams = []) : Response` +- `directMessagesSent(array $options = []) : Response` +- `favoritesCreate($id) : Response` +- `favoritesDestroy($id) : Response` +- `favoritesList(array $options = []) : Response` +- `followersIds($id, array $params = []) : Response` +- `friendsIds($id, array $params = []) : Response` +- `friendshipsCreate($id, array $params = []) : Response` +- `friendshipsLookup($id, array $params = []) : Response` +- `friendshipsDestroy($id) : Response` +- `listsMembers($listIdOrSlug, array $params = []) : Response` +- `listsMemberships($id, array $params = []) : Response` +- `listsSubscribers($id, array $params = []) : Response` +- `searchTweets(string $query, array $options = []) : Response` +- `statusesDestroy($id) : Response` +- `statusesHomeTimeline(array $options = []) : Response` +- `statusesMentionsTimeline(array $options = []) : Response` +- `statusesSample() : Response` +- `statusesShow($id, array $options = []) : Response` +- `statusesUpdate(string $status, $inReplyToStatusId = null, $extraAttributes = []) : Response` +- `statusesUserTimeline(array $options = []) : Response` +- `usersLookup($id, array $params = []) : Response` +- `usersSearch(string $query, array $options = []) : Response` +- `usersShow($id) : Response` + +## Proxy Properties + +The following proxy properties are allowed: + +- account +- application +- blocks +- directmessages +- favorites +- followers +- friends +- friendships +- lists +- search +- statuses +- users + +In each case, you can identify available methods for the proxy by comparing the +proxy name to the above list of methods. As an example, the `users` proxy allows +the following: + +```php +$twitter->users->lookup($id, array $params = []); +$twitter->users->search(string $query, array $options = []); +$twitter->users->show($id); +``` + +## Direct access + +The Twitter API has dozens of endpoints, some more popular and/or useful than +others. As such, we are only providing a subset of what is available. + +However, we allow you to access any endpoint via either the `get()` or `post()` +methods, which have the following signatures: + +```php +public function get(string $path, array $query = []) : Response; +public function post(string $path, $data = null) : Response; +``` + +In each case, the `$path` is the API endpoint as detailed in the Twitter API +documentation, minus any `.json` suffix, and the method name corresponds to +whether the request happens via HTTP GET or POST. + +For HTTP GET requests, the `$query` argument provides any query string +parameters you want to pass for that endpoint. As an example, if you were +requesting `statuses/home_timeline`, you might pass `count` or `since_id`. + +For HTTP POST requests, the `$data` argument can be one of: + +- An associative array of data. +- A serializable object of data. +- A string representing the raw payload. + +The data to provide will vary based on the endpoint. + +## Media uploads + +Since version 3.0, we have supported media uploads via the classes +`ZendService\Twitter\Media`, `Image`, and `Video`. In each case, you will +instantiate the appropriate class with the local filesystem path of the image to +upload and the media type, followed by calling `upload()` with a properly +configured HTTP client. The response will contain a `media_id` property, which +you can then provide via the `media_ids` parameter when posting a status: + + +```php +$image = new Image('data/logo.png', 'image/png'); +$response = $image->upload($twitter->getHttpClient()); + +$twitter->statusUpdate( + 'A post with an image', + null, + ['media_ids' => [$response->media_id]] +); +``` + +When providing media for direct messages, you must provide additional flags to +the media class's constructor: + +- A flag indicating it is for a direct message +- A flag indicating whether or not the uploaded media may be shared/re-used in + other direct messages. + +```php +$image = new Image( + 'data/logo.png', + 'image/png', + $forDirectMessage = true, + $shared = false +); +$upload = $image->upload($twitter->getHttpClient()); +``` + +Unlike non-DM media uploads, the identifier will be in the `id_str` parameter of +the returned upload instance; use that as a `media_id` in your DM: + +```php +$twitter->directmessagesEventsNew( + $user, + $message, + ['media_id' => $upload->id_str] +); +``` + +Note: direct messages only support a single attachment. + +## Rate limiting + +As of version 3.0, we now provide introspection of Twitter's rate limit headers, +allowing you to act on them: + +```php +$response = $twitter->statusUpdate('A post'); +$rateLimit = $response->getRateLimit(); +if ($rateLimit->remaining === 0) { + // Time to back off! + sleep($rateLimit->reset); // seconds left until reset +} +``` diff --git a/docs/ISSUE_TEMPLATE.md b/docs/ISSUE_TEMPLATE.md index ff8029d..187f844 100644 --- a/docs/ISSUE_TEMPLATE.md +++ b/docs/ISSUE_TEMPLATE.md @@ -1,11 +1,19 @@ + - [ ] I was not able to find an [open](https://github.com/zendframework/ZendService_Twitter/issues?q=is%3Aopen) or [closed](https://github.com/zendframework/ZendService_Twitter/issues?q=is%3Aclosed) issue matching what I'm seeing. + - [ ] This is not a question. (Questions should be asked on [slack](https://zendframework.slack.com/) ([Signup for Slack here](https://zendframework-slack.herokuapp.com/)) or our [forums](https://discourse.zendframework.com/).) + Provide a narrative description of what you are trying to accomplish. ### Code to reproduce the issue + + ```php ``` ### Expected results + + ### Actual results + diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md index 8859a86..f00d90c 100644 --- a/docs/PULL_REQUEST_TEMPLATE.md +++ b/docs/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,25 @@ Provide a narrative description of what you are trying to accomplish: -- Are you fixing a bug? - - Detail how the bug is invoked currently. - - Detail the original, incorrect behavior. - - Detail the new, expected behavior. +- [ ] Are you fixing a bug? + - [ ] Detail how the bug is invoked currently. + - [ ] Detail the original, incorrect behavior. + - [ ] Detail the new, expected behavior. + - [ ] Base your feature on the `master` branch, and submit against that branch. + - [ ] Add a regression test that demonstrates the bug, and proves the fix. + - [ ] Add a `CHANGELOG.md` entry for the fix. -- Are you creating a new feature? - - Why is the new feature needed? What purpose does it serve? - - How will users use the new feature? +- [ ] Are you creating a new feature? + - [ ] Why is the new feature needed? What purpose does it serve? + - [ ] How will users use the new feature? + - [ ] Base your feature on the `develop` branch, and submit against that branch. + - [ ] Add only one feature per pull request; split multiple features over multiple pull requests + - [ ] Add tests for the new feature. + - [ ] Add documentation for the new feature. + - [ ] Add a `CHANGELOG.md` entry for the new feature. -- Is this related to quality assurance? - - Detail why the changes are necessary. +- [ ] Is this related to quality assurance? + -- Is this related to documentation? - - Is it a typographical and/or grammatical fix? - - Is it new documentation? +- [ ] Is this related to documentation? + + diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md index f33fe7f..c2054c6 100644 --- a/docs/SUPPORT.md +++ b/docs/SUPPORT.md @@ -5,9 +5,9 @@ Zend Framework offers three support channels: - For real-time questions, use our [Slack](https://zendframework-slack.herokuapp.com) - For detailed questions (e.g., those requiring examples) use our - [forums](https://discourse.zendframework.com/c/contributors) + [forums](https://discourse.zendframework.com/c/questions/components) - To report issues, use this repository's - [issue tracker](https://github.com/{org}/{repo}/issues/new) + [issue tracker](https://github.com/zendframework/ZendService_Twitter/issues/new) **DO NOT** use the issue tracker to ask questions; use Slack or the forums for that. Questions posed to the issue tracker will be closed.