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="http://apiwiki.twitter.com/Twitter-API-Documentation">Twitter
            <acronym>REST</acronym> <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> implements a <acronym>REST</acronym>
            service, and all methods return an instance of
            <classname>Zend_Rest_Client_Result</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> makes sure that your account credentials are valid, checks
                    your <acronym>API</acronym> rate limit, and ends the current session for the
                    authenticated user.
                </para>
            </listitem>

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

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

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

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

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

            <listitem>
                <para>
                    <code>block</code> blocks and unblocks users from following you.
                </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(
    'username' => 'johndoe',
    'accessToken' => $token
));

// 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>
    </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(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->account->verifyCredentials();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>endSession()</methodname> signs users out of
                    client-facing applications.
                </para>

                <example id="zend.service.twitter.account.endsession">
                    <title>Sessions ending</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->account->endSession();
]]></programlisting>
                </example>
            </listitem>

            <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.account.ratelimitstatus">
                    <title>Rating limit status</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->account->rateLimitStatus();
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>publicTimeline()</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.status.publictimeline">
                    <title>Retrieving public timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->publicTimeline();
]]></programlisting>
                </example>
            </listitem>

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

                <example id="zend.service.twitter.status.friendstimeline">
                    <title>Retrieving friends timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->friendsTimeline();
]]></programlisting>
                </example>

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

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

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </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.status.usertimeline">
                    <title>Retrieving user timeline</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->userTimeline();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>id</code> specifies the ID or screen name of the user for whom to
                            return the friends_timeline.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since</code> narrows the returned results to just those statuses
                            created after the specified date/time (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>count</code> specifies the number of statuses to retrieve.
                            May not be greater than 200.
                        </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.status.show">
                    <title>Showing user status</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->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.status.update">
                    <title>Updating user status</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->update('My Great Tweet');
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>in_reply_to_status_id</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>replies()</methodname> returns the 20 most recent @replies (status
                    updates prefixed with @username) for the authenticating user.
                </para>

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

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->replies();
]]></programlisting>
                </example>

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

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

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <code>since_id</code> returns only statuses with an ID greater than
                            (that is, more recent than) the specified ID.
                        </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.status.destroy">
                    <title>Deleting user status</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->status->destroy(12345);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>friends()</methodname>r eturns up to 100 of the authenticating
                    user's friends who have most recently updated, each with current status inline.
                </para>

                <example id="zend.service.twitter.user.friends">
                    <title>Retrieving user friends</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->user->friends();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>id</code> specifies the ID or screen name of the user for whom to
                            return a list of friends.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since</code> narrows the returned results to just those statuses
                            created after the specified date/time (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>followers()</methodname> returns the authenticating user's
                    followers, each with current status inline.
                </para>

                <example id="zend.service.twitter.user.followers">
                    <title>Retrieving user followers</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->user->followers();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>id</code> specifies the ID or screen name of the user for whom to
                            return a list of followers.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <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.user.show">
                    <title>Showing user informations</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->user->show('myfriend');
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.directmessage">
        <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.directmessage.messages">
                    <title>Retrieving recent direct messages received</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->directMessage->messages();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> returns only direct messages with an ID greater
                            than (that is, more recent than) the specified ID.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since</code> narrows the returned results to just those statuses
                            created after the specified date/time (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </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.directmessage.sent">
                    <title>Retrieving recent direct messages sent</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->directMessage->sent();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>since_id</code> returns only direct messages with an ID greater
                            than (that is, more recent than) the specified ID.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>since</code> narrows the returned results to just those statuses
                            created after the specified date/time (up to 24 hours old).
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </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.directmessage.new">
                    <title>Sending direct message</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->directMessage->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.directmessage.destroy">
                    <title>Deleting direct message</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->directMessage->destroy(123548);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.friendship">
        <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.friendship.create">
                    <title>Creating friend</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->friendship->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.friendship.destroy">
                    <title>Deleting friend</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->friendship->destroy('myoldfriend');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <methodname>exists()</methodname> tests if a friendship exists between the
                    user specified in the <code>id</code> parameter and the authenticating user.
                </para>

                <example id="zend.service.twitter.friendship.exists">
                    <title>Checking friend existence</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->friendship->exists('myfriend');
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.twitter.favorite">
        <title>Favorite Methods</title>

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

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

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->favorite->favorites();
]]></programlisting>
                </example>

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

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>id</code> specifies the ID or screen name of the user for whom to
                            request a list of favorite statuses.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>page</code> specifies which page you want to return.
                        </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.favorite.create">
                    <title>Creating favorites</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->favorite->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.favorite.destroy">
                    <title>Deleting favorites</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->favorite->destroy(12351);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>exists()</methodname> checks if the authenticating user is blocking
                    a target user and can optionally return the blocked user's object if a
                    block does exists.
                </para>

                <example id="zend.service.twitter.block.exists">
                    <title>Checking if block exists</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));

// 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);
]]></programlisting>
                </example>

                <para>
                    The <methodname>favorites()</methodname> method accepts a second
                    optional parameter.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>returnResult</code> specifies whether or not return the user
                            object instead of just <constant>TRUE</constant> or
                            <constant>FALSE</constant>.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <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 in the requested
                    format when successful.
                </para>

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

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->block->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.block.destroy">
                    <title>Removing a block</title>

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));
$response   = $twitter->block->destroy('blockeduser');
]]></programlisting>
                </example>
            </listitem>

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

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

                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter(array(
    'username' => 'johndoe',
    'accessToken' => $token
));

// 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);
]]></programlisting>
                </example>

                <para>
                    The <methodname>favorites()</methodname> method accepts two optional parameters.
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>page</code> specifies which page ou want to return. A single page
                            contains 20 IDs.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <code>returnUserIds</code> specifies whether to return an array of
                            numeric user IDs the authenticating user is blocking instead of an
                            array of user objects.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>
        </itemizedlist>
    </sect2>

    <xi:include href="Zend_Service_Twitter_Search.xml" />
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->