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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.gdata.clientlogin">
    <title>Authenticating with ClientLogin</title>

    <para>
        The ClientLogin mechanism enables you to write <acronym>PHP</acronym> application
        that acquire authenticated access to Google Services,
        specifying a user's credentials in the <acronym>HTTP</acronym> Client.
    </para>

    <para>
        See <ulink
            url="http://code.google.com/apis/accounts/AuthForInstalledApps.html">http://code.google.com/apis/accounts/AuthForInstalledApps.html</ulink>
        for more information about Google Data ClientLogin authentication.
    </para>

    <para>
        The Google documentation says the ClientLogin mechanism is appropriate
        for "installed applications" whereas the AuthSub mechanism is
        for "web applications." The difference is that AuthSub requires
        interaction from the user, and a browser interface that can react
        to redirection requests. The ClientLogin solution uses <acronym>PHP</acronym> code to
        supply the account credentials; the user is not required to enter her
        credentials interactively.
    </para>

    <para>
        The account credentials supplied via the ClientLogin mechanism must
        be valid credentials for Google services, but they are not required
        to be those of the user who is using the <acronym>PHP</acronym> application.
    </para>

    <sect2 id="zend.gdata.clientlogin.login">
        <title>Creating a ClientLogin authenticated Http Client</title>

        <para>
            The process of creating an authenticated <acronym>HTTP</acronym> client using
            the ClientLogin mechanism is to call the static function
            <methodname>Zend_Gdata_ClientLogin::getHttpClient()</methodname>
            and pass the Google account credentials in plain text.
            The return value of this function is an object of class
            <classname>Zend_Http_Client</classname>.
        </para>

        <para>
            The optional third parameter is the name of the Google Data
            service. For instance, this can be 'cl' for Google Calendar.
            The default is "xapi", which is recognized by Google Data
            servers as a generic service name.
        </para>

        <para>
            The optional fourth parameter is an instance of <classname>Zend_Http_Client</classname>.
            This allows you to set options in the client, such as proxy
            server settings. If you pass <constant>NULL</constant> for this
            parameter, a generic <classname>Zend_Http_Client</classname> object is created.
        </para>

        <para>
            The optional fifth parameter is a short string that Google Data
            servers use to identify the client application for logging
            purposes. By default this is string "Zend-ZendFramework";
        </para>

        <para>
            The optional sixth parameter is a string ID for a
            <trademark>CAPTCHA</trademark> challenge that has been issued by
            the server. It is only necessary when logging in after receiving
            a <trademark>CAPTCHA</trademark> challenge from a previous
            login attempt.
        </para>

        <para>
            The optional seventh parameter is a user's response to a
            <trademark>CAPTCHA</trademark> challenge that has been issued by
            the server. It is only necessary when logging in after receiving
            a <trademark>CAPTCHA</trademark> challenge from a previous
            login attempt.
        </para>

        <para>
            Below is an example of <acronym>PHP</acronym> code for a web application
            to acquire authentication to use the Google Calendar service
            and create a <classname>Zend_Gdata</classname> client object using that authenticated
            <classname>Zend_Http_Client</classname>.
        </para>

        <programlisting language="php"><![CDATA[
// Enter your Google account credentials
$email = 'johndoe@gmail.com';
$passwd = 'xxxxxxxx';
try {
   $client = Zend_Gdata_ClientLogin::getHttpClient($email, $passwd, 'cl');
} catch (Zend_Gdata_App_CaptchaRequiredException $cre) {
    echo 'URL of CAPTCHA image: ' . $cre->getCaptchaUrl() . "\n";
    echo 'Token ID: ' . $cre->getCaptchaToken() . "\n";
} catch (Zend_Gdata_App_AuthException $ae) {
   echo 'Problem authenticating: ' . $ae->exception() . "\n";
}

$cal = new Zend_Gdata_Calendar($client);
]]></programlisting>
    </sect2>

    <sect2 id="zend.gdata.clientlogin.terminating">
        <title>Terminating a ClientLogin authenticated Http Client</title>

        <para>
            There is no method to revoke ClientLogin authentication as there
            is in the AuthSub token-based solution. The credentials used
            in the ClientLogin authentication are the login and password
            to a Google account, and therefore these can be used repeatedly
            in the future.
        </para>
    </sect2>
</sect1>