repo_zf1Php7/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/REST+API+Documentation">Twitter REST API</ulink>.
            <classname>Zend_Service_Twitter</classname> 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.
        </para>

        <para>
            <classname>Zend_Service_Twitter</classname> is implementing a REST 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>, make sure that your account credentials are valid, check your api rate limit
                    and end the current session for the authenticated user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>status</code>, retrieves the public and user timelines and allows you to show, update, destroy
                    and retrieve replies for the authenticated user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>user</code>, retrieves the friends, followers for the authenticated user. With the
                    show method you can return extended information about the passed in user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>directMessage</code>, retrieves the authenticated users received direct message and allows you to send and
                    delete new direct message.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>friendship</code>, create or remove a friendship for the authenticated user.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>favorite</code>, list, create or remove a favorite tweet.
                </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 to work. Twitter currently uses <ulink
             url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">HTTP Basic Authentication</ulink>.
            You can pass in your username or registered email along with your password for twitter to login.
        </para>

        <example id="zend.service.twitter.authentication.example">
            <title>Creating the Twitter Class</title>
            <para>
                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.
            </para>

            <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
// verify your credentials with twitter
$response = $twitter->account->verifyCredentials();
]]></programlisting>
        </example>
    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>verifyCredentials</code>, Use this method to test 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('myusername', 'mysecretpassword');
$response = $twitter->account->verifyCredentials();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>endSession</code>, Use this method to sign 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('myusername', 'mysecretpassword');
$response = $twitter->account->endSession();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>rateLimitStatus</code>, Returns the remaining number of API requests available to the authenticating user
                    before the API 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('myusername', 'mysecretpassword');
$response = $twitter->account->rateLimitStatus();
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>publicTimeline</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->status->publicTimeline();
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>friendsTimeline</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->status->friendsTimeline();
]]></programlisting>
                </example>

                <para>The <code>friendsTimeline</code> 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>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>

            </listitem>

            <listitem>
                <para>
                    <code>userTimeline</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->status->userTimeline();
]]></programlisting>
                </example>

                <para>The <code>userTimeline</code> 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>, 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>
                    <code>show</code>, 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.
                </para>

                <example id="zend.service.twitter.status.show">
                    <title>Showing user status</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->status->show(1234);
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>update</code>, 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.
                </para>

                <example id="zend.service.twitter.status.update">
                    <title>Updating user status</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->status->update('My Great Tweet');
]]></programlisting>
                </example>

                <para>The <code>update</code> method accepts a second additional parameter.</para>

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

            <listitem>
                <para>
                    <code>replies</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->status->replies();
]]></programlisting>
                </example>

                <para>The <code>replies</code> 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>, 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>
                    <code>destroy</code>, Destroys the status specified by the required ID parameter.
                </para>

                <example id="zend.service.twitter.status.destroy">
                    <title>Deleting user status</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->status->destroy(12345);
]]></programlisting>
                </example>
            </listitem>
        </itemizedlist>

    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>friends</code>, Returns 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('myusername', 'mysecretpassword');
$response = $twitter->user->friends();
]]></programlisting>
                </example>

                <para>The <code>friends</code> 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>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <code>followers</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->user->followers();
]]></programlisting>
                </example>

                <para>The <code>followers</code> 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>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>

            </listitem>

            <listitem>
                <para>
                    <code>show</code>, Returns extended information of a given user, specified by ID or screen name as per the
                    required id parameter below
                </para>

                <example id="zend.service.twitter.user.show">
                    <title>Showing user informations</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->user->show('myfriend');
]]></programlisting>
                </example>

            </listitem>

        </itemizedlist>

    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>messages</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->directMessage->messages();
]]></programlisting>
                </example>

                <para>The <code>message</code> 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>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <code>sent</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->directMessage->sent();
]]></programlisting>
                </example>

                <para>The <code>sent</code> 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>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <code>new</code>, 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('myusername', 'mysecretpassword');
$response = $twitter->directMessage->new('myfriend', 'mymessage');
]]></programlisting>
                </example>

            </listitem>

            <listitem>
                <para>
                    <code>destroy</code>, Destroys the direct message specified in the required ID 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('myusername', 'mysecretpassword');
$response = $twitter->directMessage->destroy(123548);
]]></programlisting>
                </example>

            </listitem>

        </itemizedlist>

    </sect2>

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

        <itemizedlist>
            <listitem>
                <para>
                    <code>create</code>, Befriends the user specified in the ID parameter as the authenticating user.
                </para>

                <example id="zend.service.twitter.friendship.create">
                    <title>Creating friend</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->friendship->create('mynewfriend');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>destroy</code>, Discontinues friendship with the user specified in the ID parameter as the authenticating user.
                </para>

                <example id="zend.service.twitter.friendship.destroy">
                    <title>Deleting friend</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->friendship->destroy('myoldfriend');
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>exists</code>, Tests if a friendship exists between the authenticated user and the passed in user.
                </para>

                <example id="zend.service.twitter.friendship.exists">
                    <title>Checking friend existence</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->friendship->exists('myfriend');
]]></programlisting>
                </example>

            </listitem>

        </itemizedlist>

    </sect2>

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

        <itemizedlist>

            <listitem>
                <para>
                    <code>favorites</code>, Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter
                </para>

                <example id="zend.service.twitter.favorite.favorites">
                    <title>Retrieving favorites</title>
                    <programlisting language="php"><![CDATA[
$twitter = new Zend_Service_Twitter('myusername', 'mysecretpassword');
$response = $twitter->favorite->favorites();
]]></programlisting>
                </example>

                <itemizedlist>
                    <listitem>
                        <para>
                            <code>id</code>, The ID or screen name of the user for whom to request a list of favorite statuses.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <code>page</code>, Which page you want to return.
                        </para>
                    </listitem>
                </itemizedlist>

            </listitem>

            <listitem>
                <para>
                    <code>create</code>, Favorites the status specified in the ID 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('myusername', 'mysecretpassword');
$response = $twitter->favorite->create(12351);
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>destroy</code>, Un-favorites the status specified in the ID 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('myusername', 'mysecretpassword');
$response = $twitter->favorite->destroy(12351);
]]></programlisting>
                </example>
            </listitem>

        </itemizedlist>

    </sect2>

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