# Zend_Service_Twitter

## Introduction

`Zend_Service_Twitter` provides a client for the Twitter REST API. `Zend_Service_Twitter` allows you to query the public timeline. If you provide a username and password for Twitter, it will allow you to get and update your status, reply to friends, direct message friends, mark tweets as favorite, and much more.

`Zend_Service_Twitter` is implementing a REST service, and all methods return an instance of `Zend_Rest_Client_Result`.

`Zend_Service_Twitter` is broken up into subsections so you can easily identify which type of call is being requested.

- `account` makes sure that your account credentials are valid, checks your API rate limit, and ends the current session for the authenticated user.

- `status` retrieves the public and user timelines and shows, updates, destroys, and retrieves replies for the authenticated user.

- `user` retrieves friends and followers for the authenticated user and returns extended information about a passed user.

- `directMessage` retrieves the authenticated user's received direct messages, deletes direct messages, and sends new direct messages.

- `friendship` creates and removes friendships for the authenticated user.

- `favorite` lists, creates, and removes favorite tweets.

- `block` blocks and unblocks users from following you.

## Authentication

With the exception of fetching the public timeline, `Zend_Service_Twitter` requires authentication to work. Twitter currently uses HTTP Basic Authentication. You can pass in your username or registered email along with your password for Twitter to login.

### Creating the Twitter Class

The following code sample is how you create the Twitter service, pass in your username and password, and verify that they are correct.

    $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');

    // verify your credentials with Twitter
    $response = $twitter->account->verifyCredentials();

You can also pass in an array that contains the username and password as the first argument.

    $userInfo   = array('username' => 'foo', 'password' => 'bar');
    $twitter    = new Zend_Service_Twitter($userInfo);

    // verify your credentials with Twitter
    $response = $twitter->account->verifyCredentials();

## Account Methods

- `verifyCredentials()` tests if supplied user credentials are valid with minimal overhead.

  ### Verifying credentials

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->account->verifyCredentials();

- `endSession()` signs users out of client-facing applications.

  ### Sessions ending

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->account->endSession();

- `rateLimitStatus()` returns the remaining number of API requests available to the authenticating user before the API limit is reached for the current hour.

  ### Rating limit status

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->account->rateLimitStatus();

## Status Methods

- `publicTimeline()` returns the 20 most recent statuses from non-protected users with a custom user icon. The public timeline is cached by Twitter for 60 seconds.

  ### Retrieving public timeline

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->publicTimeline();

- `friendsTimeline()` returns the 20 most recent statuses posted by the authenticating user and that user's friends.

  ### Retrieving friends timeline

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->friendsTimeline();

  The `friendsTimeline()` method accepts an array of optional parameters to modify the query.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

- `userTimeline()` returns the 20 most recent statuses posted from the authenticating user.

  ### Retrieving user timeline

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->userTimeline();

  The `userTimeline()` method accepts an array of optional parameters to modify the query.

  - `id` specifies the ID or screen name of the user for whom to return the friends_timeline.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

  - `count` specifies the number of statuses to retrieve. May not be greater than 200.

- `show()` returns a single status, specified by the `id` parameter below. The status' author will be returned inline.

  ### Showing user status

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->show(1234);

- `update()` updates the authenticating user's status. This method requires that you pass in the status update that you want to post to Twitter.

  ### Updating user status

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->update('My Great Tweet');

  The `update()` method accepts a second additional parameter.

  - `in_reply_to_status_id` specifies the ID of an existing status that the status to be posted is in reply to.

- `replies()` returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user.

  ### Showing user replies

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->replies();

  The `replies()` method accepts an array of optional parameters to modify the query.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

  - `since_id` returns only statuses with an ID greater than (that is, more recent than) the specified ID.

- `destroy()` destroys the status specified by the required `id` parameter.

  ### Deleting user status

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->status->destroy(12345);

## User Methods

- `friends()`r eturns up to 100 of the authenticating user's friends who have most recently updated, each with current status inline.

  ### Retrieving user friends

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->user->friends();

  The `friends()` method accepts an array of optional parameters to modify the query.

  - `id` specifies the ID or screen name of the user for whom to return a list of friends.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

- `followers()` returns the authenticating user's followers, each with current status inline.

  ### Retrieving user followers

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->user->followers();

  The `followers()` method accepts an array of optional parameters to modify the query.

  - `id` specifies the ID or screen name of the user for whom to return a list of followers.

  - `page` specifies which page you want to return.

- `show()` returns extended information of a given user, specified by ID or screen name as per the required `id` parameter below.

  ### Showing user informations

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->user->show('myfriend');

## Direct Message Methods

- `messages()` returns a list of the 20 most recent direct messages sent to the authenticating user.

  ### Retrieving recent direct messages received

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->directMessage->messages();

  The `message()` method accepts an array of optional parameters to modify the query.

  - `since_id` returns only direct messages with an ID greater than (that is, more recent than) the specified ID.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

- `sent()` returns a list of the 20 most recent direct messages sent by the authenticating user.

  ### Retrieving recent direct messages sent

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->directMessage->sent();

  The `sent()` method accepts an array of optional parameters to modify the query.

  - `since_id` returns only direct messages with an ID greater than (that is, more recent than) the specified ID.

  - `since` narrows the returned results to just those statuses created after the specified date/time (up to 24 hours old).

  - `page` specifies which page you want to return.

- `new()` sends a new direct message to the specified user from the authenticating user. Requires both the user and text parameters below.

  ### Sending direct message

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->directMessage->new('myfriend', 'mymessage');

- `destroy()` destroys the direct message specified in the required `id` parameter. The authenticating user must be the recipient of the specified direct message.

  ### Deleting direct message

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->directMessage->destroy(123548);

## Friendship Methods

- `create()` befriends the user specified in the `id` parameter with the authenticating user.

  ### Creating friend

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->friendship->create('mynewfriend');

- `destroy()` discontinues friendship with the user specified in the `id` parameter and the authenticating user.

  ### Deleting friend

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->friendship->destroy('myoldfriend');

- `exists()` tests if a friendship exists between the user specified in the `id` parameter and the authenticating user.

  ### Checking friend existence

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->friendship->exists('myfriend');

## Favorite Methods

- `favorites()` returns the 20 most recent favorite statuses for the authenticating user or user specified by the `id` parameter.

  ### Retrieving favorites

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->favorite->favorites();

  The `favorites()` method accepts an array of optional parameters to modify the query.

  - `id` specifies the ID or screen name of the user for whom to request a list of favorite statuses.

  - `page` specifies which page you want to return.

- `create()` favorites the status specified in the `id` parameter as the authenticating user.

  ### Creating favorites

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->favorite->create(12351);

- `destroy()` un-favorites the status specified in the `id` parameter as the authenticating user.

  ### Deleting favorites

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->favorite->destroy(12351);

## Block Methods

- `exists()` checks if the authenticating user is blocking a target user and can optionally return the blocked user's object if a block does exists.

  ### Checking if block exists

      $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');

      // returns true or false
      $response = $twitter->block->exists('blockeduser');

      // returns the blocked user's info if the user is blocked
      $response2 = $twitter->block->exists('blockeduser', true);

  The `favorites()` method accepts a second optional parameter.

  - `returnResult` specifies whether or not return the user object instead of just `TRUE` or `FALSE`.

- `create()` blocks the user specified in the `id` parameter as the authenticating user and destroys a friendship to the blocked user if one exists. Returns the blocked user in the requested format when successful.

  ### Blocking a user

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->block->create('usertoblock);

- `destroy()` un-blocks the user specified in the `id` parameter for the authenticating user. Returns the un-blocked user in the requested format when successful.

  ### Removing a block

      $twitter    = new Zend_Service_Twitter('myusername', 'mysecretpassword');
      $response   = $twitter->block->destroy('blockeduser');

- `blocking()` returns an array of user objects that the authenticating user is blocking.

  ### Who are you blocking

      $twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');

      // return the full user list from the first page
      $response = $twitter->block->blocking();

      // return an array of numeric user IDs from the second page
      $response2 = $twitter->block->blocking(2, true);

  The `favorites()` method accepts two optional parameters.

  - `page` specifies which page ou want to return. A single page contains 20 IDs.

  - `returnUserIds` specifies whether to return an array of numeric user IDs the authenticating user is blocking instead of an array of user objects.