Synced support documentation and provided initial usage documentation

.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

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' => '<token value>',
+        'secret' => '<token secret value>',
+    ],
+    'oauth_options' => [
+        'consumerKey' => '<consumer key value>',
+        'consumerSecret' => '<consumer secret value>',
+    ],
+]);
+```
+
+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
+}
+```

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
 
+<!-- Please provide the minimum code necessary to recreate the issue -->
+
 ```php
 ```
 
 ### Expected results
 
+<!-- What do you think should have happened? -->
+
 ### Actual results
 
+<!-- What did you actually observe? -->

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?
+  <!-- Detail why the changes are necessary -->
 
-- Is this related to documentation?
-  - Is it a typographical and/or grammatical fix?
-  - Is it new documentation?
+- [ ] Is this related to documentation?
+  <!-- Is it a typographical and/or grammatical fix? -->
+  <!-- Is it new documentation? -->

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.