repo_zf1/documentation/manual/en/module_specs/Zend_Service_Twitter.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.twitter" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Zend_Service_Twitter</title>

    <sect2 id="zend.service.twitter.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Service_Twitter</classname> provides a client for the
            <ulink url="https://dev.twitter.com/docs/api/1.1">Twitter <acronym>API</acronym></ulink>.
            <classname>Zend_Service_Twitter</classname> allows you to query the public timeline. If
            you provide a username and OAuth details 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.
        </para>

        <para>
            <classname>Zend_Service_Twitter</classname> wraps all web service
            operations, including OAuth, and all methods return an instance of
            <classname>Zend_Service_Twitter_Response</classname>.
        </para>

        <para>
            <classname>Zend_Service_Twitter</classname> is broken up into subsections so you can
            easily identify which type of call is being requested.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>account</code> allows you to check that your account credentials are
                    valid.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>application</code> allows you to check your <acronym>API</acronym> rate
                    limit.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>blocks</code> blocks and unblocks users from following you.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>directMessages</code> retrieves the authenticated user's received direct
                    messages, deletes direct messages, and sends new direct messages.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>favorites</code> lists, creates, and removes favorite tweets.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>friendships</code> creates and removes friendships for the
                    authenticated user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>search</code> allows you to search statuses for specific criteria.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>statuses</code> retrieves the public and user timelines and
                    shows, updates, destroys, and retrieves replies for the authenticated user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>users</code> retrieves friends and followers for the authenticated user
                    and returns extended information about a passed user.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.authentication">
        <title>Authentication</title>

        <para>
            With the exception of fetching the public timeline,
            <classname>Zend_Service_Twitter</classname> requires authentication as a valid
            user. This is achieved using the OAuth authentication protocol. OAuth is
            the only supported authentication mode for Twitter as of August 2010. The OAuth
            implementation used by <classname>Zend_Service_Twitter</classname> is
            <classname>Zend_Oauth</classname>.
        </para>

        <example id="zend.service.twitter.authentication.example">
            <title>Creating the Twitter Class</title>

            <para>
                <classname>Zend_Service_Twitter</classname> must authorize itself, on behalf of a user, before use with the
                Twitter API (except for public timeline). This must be accomplished using OAuth since
                Twitter has disabled it's basic HTTP authentication as of August 2010.
            </para>

            <para>
                There are two options to establishing authorization. The first is to implement the
                workflow of <classname>Zend_Oauth</classname> via <classname>Zend_Service_Twitter</classname>
                which proxies to an internal <classname>Zend_Oauth_Consumer</classname> object. Please refer to
                the <classname>Zend_Oauth</classname> documentation for a full example of this
                workflow - you can call all documented <classname>Zend_Oauth_Consumer</classname> methods
                on <classname>Zend_Service_Twitter</classname> including constructor options. You may also
                use <classname>Zend_Oauth</classname> directly and only pass the resulting access
                token into <classname>Zend_Service_Twitter</classname>. This is the normal workflow
                once you have established a reusable access token for a particular Twitter user. The resulting OAuth
                access token should be stored to a database for future use (otherwise you will need to
                authorize for every new instance of <classname>Zend_Service_Twitter</classname>). Bear in mind
                that authorization via OAuth results in your user being redirected to Twitter to give their
                consent to the requested authorization (this is not repeated for stored access tokens). This will
                require additional work (i.e. redirecting users and hosting a callback URL) over the previous
                HTTP authentication mechanism where a user just
                needed to allow applications to store their username and password.
            </para>

            <para>The following example demonstrates setting up <classname>Zend_Service_Twitter</classname>
            which is given an already established OAuth access token. Please refer to the <classname>Zend_Oauth</classname>
            documentation to understand the workflow involved. The access token is a serializable object, so you may
            store the serialized object to a database, and unserialize it at retrieval time before passing the objects
            into <classname>Zend_Service_Twitter</classname>. The <classname>Zend_Oauth</classname> documentation
            demonstrates the workflow and objects involved.</para>

            <programlisting language="php"><![CDATA[
/**
 * We assume $serializedToken is the serialized token retrieved from a database
 * or even $_SESSION (if following the simple Zend_Oauth documented example)
 */
$token = unserialize($serializedToken);

$twitter = new Zend_Service_Twitter(array(
    'accessToken' => $token
    'oauth_options' => array(
        'username' => 'johndoe',
    ),
));

// verify user's credentials with Twitter
$response = $twitter->account->verifyCredentials();
]]></programlisting>
        </example>

        <note>
            <para>
                In order to authenticate with Twitter, ALL applications MUST be registered with
                Twitter in order to receive a Consumer Key and Consumer Secret to be used when
                authenticating with OAuth. This can not be reused across multiple applications -
                you must register each new application separately. Twitter access tokens have
                no expiry date, so storing them to a database is advised (they can, of course,
                be refreshed simply be repeating the OAuth authorization process). This can only
                be done while interacting with the user associated with that access token.
            </para>

            <para>
                The previous pre-OAuth version of <classname>Zend_Service_Twitter</classname>
                allowed passing in a username as the first parameter rather than within an array.
                This is no longer supported.
            </para>
        </note>

        <para>
            If you have registered an application with Twitter, you can also use the access token
            and access token secret they provide you in order to setup the OAuth consumer. This can
            be done as follows:
        </para>

        <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'access_token' => array( // or use "accessToken" as the key; both work
        'token' => 'your-access-token',
        'secret' => 'your-access-token-secret',
    ),
    'oauth_options' => array( // or use "oauthOptions" as the key; both work
        'consumerKey' => 'your-consumer-key',
        'consumerSecret' => 'your-consumer-secret',
    ),
));
]]></programlisting>

        <para>
            If desired, you can also specify a specific HTTP client instance to use, or provide
            configuration for the HTTP client. To provide the HTTP client, use the
            <varname>http_client</varname> or <varname>httpClient</varname> key, and provide an
            instance. To provide HTTP client configuration for setting up an instance, use the key
            <varname>http_client_options</varname> or <varname>httpClientOptions</varname>. As a
            full example:
        </para>

        <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'access_token' => array( // or use "accessToken" as the key; both work
        'token' => 'your-access-token',
        'secret' => 'your-access-token-secret',
    ),
    'oauth_options' => array( // or use "oauthOptions" as the key; both work
        'consumerKey' => 'your-consumer-key',
        'consumerSecret' => 'your-consumer-secret',
    ),
    'http_client_options' => array(
        'adapter' => 'Zend_Http_Client_Adapter_Curl',
    ),
));
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.twitter.account">
        <title>Account Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>verifyCredentials()</methodname> tests if supplied user
                    credentials are valid with minimal overhead.
                </para>

                <example id="zend.service.twitter.account.verifycredentails">
                    <title>Verifying credentials</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->account->verifyCredentials();
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.application">
        <title>Application Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>rateLimitStatus()</methodname> returns the remaining number of
                    <acronym>API</acronym> requests available to the authenticating user
                    before the <acronym>API</acronym> limit is reached for the current hour.
                </para>

                <example id="zend.service.twitter.application.ratelimitstatus">
                    <title>Rating limit status</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->application->rateLimitStatus();
$userTimelineLimit = $response->resources->statuses->{'/statuses/user_timeline'}->remaining;
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.blocks">
        <title>Block Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>create()</methodname> blocks the user specified in the
                    <code>id</code> parameter as the authenticating user and destroys a friendship
                    to the blocked user if one exists. Returns the blocked user when successful.
                </para>

                <example id="zend.service.twitter.blocks.create">
                    <title>Blocking a user</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->blocks->create('usertoblock');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>destroy()</methodname> un-blocks the user specified in the
                    <code>id</code> parameter for the authenticating user. Returns the un-blocked
                    user in the requested format when successful.
                </para>

                <example id="zend.service.twitter.blocks.destroy">
                    <title>Removing a block</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->blocks->destroy('blockeduser');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>ids()</methodname> returns an array of user identifiers that the
                    authenticating user is blocking.
                </para>

                <example id="zend.service.twitter.blocks.ids">
                    <title>Who are you blocking (identifiers only)</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->blocks->ids();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>list()</methodname> returns an array of user objects that the
                    authenticating user is blocking.
                </para>

                <example id="zend.service.twitter.blocks.list">
                    <title>Who are you blocking</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->blocks->list();
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.directmessages">
        <title>Direct Message Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>messages()</methodname> returns a list of the 20 most recent direct
                    messages sent to the authenticating user.
                </para>

                <example id="zend.service.twitter.directmessages.messages">
                    <title>Retrieving recent direct messages received</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->directMessages->messages();
]]></programlisting>
                </example>

                <para>
                    The <methodname>messages()</methodname> method accepts an array of optional
                    parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>skip_status</code>, when set to boolean true, "t", or 1 will skip
                            including a user's most recent status in the results.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>sent()</methodname> returns a list of the 20 most recent direct
                    messages sent by the authenticating user.
                </para>

                <example id="zend.service.twitter.directmessages.sent">
                    <title>Retrieving recent direct messages sent</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->directMessages->sent();
]]></programlisting>
                </example>

                <para>
                    The <methodname>sent()</methodname> method accepts an array of optional
                    parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 20.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies the page of results to return, based on the
                            <code>count</code> provided.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>new()</methodname> sends a new direct message to the specified user
                    from the authenticating user. Requires both the user and text parameters below.
                </para>

                <example id="zend.service.twitter.directmessages.new">
                    <title>Sending a direct message</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->directMessages->new('myfriend', 'mymessage');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>destroy()</methodname> destroys the direct message specified in the
                    required <code>id</code> parameter. The authenticating user must be the
                    recipient of the specified direct message.
                </para>

                <example id="zend.service.twitter.directmessages.destroy">
                    <title>Deleting a direct message</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->directMessages->destroy(123548);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.favorites">
        <title>Favorites Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>list()</methodname> returns the 20 most recent favorite
                    statuses for the authenticating user or user specified by the
                    <code>user_id</code> or <code>screen_name</code> parameter.
                </para>

                <example id="zend.service.twitter.favorites.list">
                    <title>Retrieving favorites</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->favorites->list();
]]></programlisting>
                </example>

                <para>
                    The <methodname>list()</methodname> method accepts an array of optional
                    parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>user_id</code> specifies the ID of the user for whom to return the
                            timeline.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>screen_name</code> specifies the screen name of the user for
                            whom to return the timeline.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>create()</methodname> favorites the status specified in the
                    <code>id</code> parameter as the authenticating user.
                </para>

                <example id="zend.service.twitter.favorites.create">
                    <title>Creating a favorite</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->favorites->create(12351);
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>destroy()</methodname> un-favorites the status specified in the
                    <code>id</code> parameter as the authenticating user.
                </para>

                <example id="zend.service.twitter.favorites.destroy">
                    <title>Deleting favorites</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->favorites->destroy(12351);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.friendships">
        <title>Friendship Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>create()</methodname> befriends the user specified in the
                    <code>id</code> parameter with the authenticating user.
                </para>

                <example id="zend.service.twitter.friendships.create">
                    <title>Creating a friend</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->friendships->create('mynewfriend');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>destroy()</methodname> discontinues friendship with the user
                    specified in the <code>id</code> parameter and the authenticating user.
                </para>

                <example id="zend.service.twitter.friendships.destroy">
                    <title>Deleting a friend</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->friendships->destroy('myoldfriend');
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.search">
        <title>Search Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>tweets()</methodname> returns a list of tweets matching the criteria
                    specified in <varname>$query</varname>. By default, 15 will be returned, but
                    this value may be changed using the <varname>count</varname> option.
                </para>

                <example id="zend.service.twitter.search.tweets">
                    <title>Searching for tweets</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->search->tweets('#zendframework');
]]></programlisting>
                </example>

                <para>
                    The <methodname>tweets()</methodname> method accepts an optional second
                    argument, an array of optional parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>lang</code> indicates which two-letter language code to restrict
                            results to.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>locale</code> indicates which two-letter language code is being
                            used in the query.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>geocode</code> can be used to indicate the geographical radius in
                            which tweets should originate; the string should be in the form
                            "latitude,longitude,radius", with "radius" being a unit followed by one
                            of "mi" or "km".
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>result_type</code> indicates what type of results to retrieve, and
                            should be one of "mixed," "recent," or "popular."
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>until</code> can be used to specify a the latest date for which to
                            return tweets.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.statuses">
        <title>Status Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>sample()</methodname> 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.
                </para>

                <example id="zend.service.twitter.statuses.sample">
                    <title>Retrieving public timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->sample();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>homeTimeline()</methodname> returns the 20 most recent statuses
                    posted by the authenticating user and that user's friends.
                </para>

                <example id="zend.service.twitter.statuses.hometimeline">
                    <title>Retrieving the home timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
));
$response = $twitter->statuses->homeTimeline();
]]></programlisting>
                </example>

                <para>
                    The <methodname>homeTimeline()</methodname> method accepts an array of
                    optional parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>trim_user</code>, when set to boolean true, "t", or 1, will list
                            the author identifier only in embedded user objects in the statuses
                            returned.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>contributor_details</code>, when set to boolean true, will return
                            the screen name of any contributors to a status (instead of only the
                            contributor identifier).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>exclude_replies</code> controls whether or not status updates that
                            are in reply to other statuses will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>userTimeline()</methodname> returns the 20 most recent statuses
                    posted from the authenticating user.
                </para>

                <example id="zend.service.twitter.statuses.usertimeline">
                    <title>Retrieving user timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->userTimeline();
]]></programlisting>
                </example>

                <para>
                    The <methodname>userTimeline()</methodname> method accepts an array of optional
                    parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>user_id</code> specifies the ID of the user for whom to return the
                            timeline.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>screen_name</code> specifies the screen name of the user for
                            whom to return the timeline.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>trim_user</code>, when set to boolean true, "t", or 1, will list
                            the author identifier only in embedded user objects in the statuses
                            returned.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>contributor_details</code>, when set to boolean true, will return
                            the screen name of any contributors to a status (instead of only the
                            contributor identifier).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_rts</code> controls whether or not to include native
                            retweets in the returned list.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>exclude_replies</code> controls whether or not status updates that
                            are in reply to other statuses will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>show()</methodname> returns a single status, specified by the
                    <code>id</code> parameter below. The status' author will be returned inline.
                </para>

                <example id="zend.service.twitter.statuses.show">
                    <title>Showing user status</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->show(1234);
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>update()</methodname> updates the authenticating user's status.
                    This method requires that you pass in the status update that you want to post
                    to Twitter.
                </para>

                <example id="zend.service.twitter.statuses.update">
                    <title>Updating user status</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->update('My Great Tweet');
]]></programlisting>
                </example>

                <para>
                    The <methodname>update()</methodname> method accepts a second additional
                    parameter.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>inReplyToStatusId</code> specifies the ID of an existing
                            status that the status to be posted is in reply to.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>mentionsTimeline()</methodname> returns the 20 most recent @replies
                    (status updates prefixed with @username) for the authenticating user.
                </para>

                <example id="zend.service.twitter.statuses.mentionstimeline">
                    <title>Showing user replies</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->mentionsTimeline();
]]></programlisting>
                </example>

                <para>
                    The <methodname>mentionsTimeline()</methodname> method accepts an array of
                    optional parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> narrows the returned results to just those
                            statuses after the specified identifier (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>max_id</code> narrows the returned results to just those
                            statuses earlier than the specified identifier.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 200.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>trim_user</code>, when set to boolean true, "t", or 1, will list
                            the author identifier only in embedded user objects in the statuses
                            returned.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>contributor_details</code>, when set to boolean true, will return
                            the screen name of any contributors to a status (instead of only the
                            contributor identifier).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>destroy()</methodname> destroys the status specified by the
                    required <code>id</code> parameter.
                </para>

                <example id="zend.service.twitter.statuses.destroy">
                    <title>Deleting user status</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->statuses->destroy(12345);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.users">
        <title>User Methods</title>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>show()</methodname> returns extended information of a given user,
                    specified by ID or screen name as per the required <code>id</code>
                    parameter below.
                </para>

                <example id="zend.service.twitter.users.show">
                    <title>Showing user informations</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->users->show('myfriend');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>search()</methodname> will search for users matching the query
                    provided.
                </para>

                <example id="zend.service.twitter.users.search">
                    <title>Searching for users</title>

                    <programlisting language="php"><![CDATA[
$twitter  = new Zend_Service_Twitter($options);
$response = $twitter->users->search('Zend');
]]></programlisting>
                </example>

                <para>
                    The <methodname>search()</methodname> method accepts an array of
                    optional parameters to modify the query.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to return, up to 20.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies the page of results to return, based on the
                            <code>count</code> provided.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>include_entities</code> controls whether or not entities, which
                            includes URLs, mentioned users, and hashtags, will be returned.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->