# Zend_Service_Twitter

## Introduction

`Zend_Service_Twitter` provides a client for the Twitter REST API. `Zend_Service_Twitter` will allow you to query the public timeline and 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`, make sure that your account credentials are valid, check your api rate limit and end the current session for the authenticated user.

- `status`, retrieves the public and user timelines and allows you to show, update, destroy and retrieve replies for the authenticated user.

- `user`, retrieves the friends, followers for the authenticated user. With the show method you can return extended information about the passed in user.

- `directMessage`, retrieves the authenticated users received direct message and allows you to send and delete new direct message.

- `friendship`, create or remove a friendship for the authenticated user.

- `favorite`, list, create or remove a favorite tweet.

## 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 and pass in your username and password and then 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 as the first variable that contains the username and password.

    						$userInfo = array('username' => 'foo', 'password' => 'bar');
    $twitter = new Zend_Service_Twitter(userInfo);
    // verify your credentials with twitter
    $response = $twitter->account->verifyCredentials();

## Account Methods

- `verifyCredentials`, Use this method to test if supplied user credentials are valid with minimal overhead.

  ### Verifying credentials

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

- `endSession`, Use this method to sign 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`, 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`, 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's author will be returned inline. This method required a tweet id to be passed in.

  ### 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. A second optional parameter is the id of the tweet that you are replying to.

  ### 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`, 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`, 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`, Returns 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`, 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`, 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`, 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`, 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 as 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 as 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 authenticated user and the passed in 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();

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

  - `page`, 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);