<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.oauth.introduction.getting-started">
    <title>Getting Started</title>

    <para>
        With the OAuth protocol explained, let's show a simple example of it with
        source code. Our new Consumer will be handling Twitter Status submissions.
        To do so, it will need to be registered with Twitter in order to receive
        an OAuth Consumer Key and Consumer Secret. This are utilised to obtain
        an Access Token before we use the Twitter API to post a status message.
    </para>
    
    <para>
        Assuming we have obtained a key and secret, we can start the OAuth workflow
        by setting up a <classname>Zend_Oauth_Consumer</classname> instance as
        follows passing it a configuration (either an array or <classname>
        Zend_Config</classname> object).
    </para>
    
    <programlisting language="php"><![CDATA[
$config = array(
    'callbackUrl' => 'http://example.com/callback.php',
    'siteUrl' => 'http://twitter.com/oauth',
    'consumerKey' => 'gg3DsFTW9OU9eWPnbuPzQ',
    'consumerSecret' => '<KEY>'
);
$consumer = new Zend_Oauth_Consumer($config);
]]></programlisting>

    <para>
        The callbackUrl is the URI we want Twitter to request from our server
        when sending information. We'll look at this later. The siteUrl is the
        base URI of Twitter's OAuth API endpoints. The full list of endpoints include
        http://twitter.com/oauth/request_token, http://twitter.com/oauth/access_token,
        and http://twitter.com/oauth/authorize. The base siteUrl utilises a convention
        which maps to these three OAuth endpoints (as standard) for requesting a
        request token, access token or authorization. If the actual endpoints of
        any service differ from the standard set, these three URIs can be separately
        set using the methods <methodname>setRequestTokenUrl()</methodname>,
        <methodname>setAccessTokenUrl()</methodname>,
        and <methodname>setAuthorizeUrl()</methodname> or the configuration fields requestTokenUrl,
        accessTokenUrl and authorizeUrl.
    </para>
    
    <para>
        The consumerKey and consumerSecret are retrieved from Twitter when your
        application is registered for OAuth access. These also apply to any OAuth
        enabled service, so each one will provide a key and secret for your
        application.
    </para>
    
    <para>
        All of these configuration options may be set using method calls simply
        by converting from, e.g. callbackUrl to setCallbackUrl().
    </para>
    
    <para>
        In addition, you should note several other configuration values not
        explicitly used: requestMethod and requestScheme. By default, <classname>
        Zend_Oauth_Consumer</classname> sends requests as POST (except for a
        redirect which uses GET). The customised client (see later) also includes its
        authorization by way of a header. Some services may, at their discretion,
        require alternatives. You can reset the requestMethod (which defaults
        to Zend_Oauth::POST) to Zend_Oauth::GET, for example, and reset the
        requestScheme from its default of Zend_Oauth::REQUEST_SCHEME_HEADER to one
        of Zend_Oauth::REQUEST_SCHEME_POSTBODY or
        Zend_Oauth::REQUEST_SCHEME_QUERYSTRING. Typically the defaults should work
        fine apart from some exceptional cases. Please refer to the service provider's
        documentation for more details.
    </para>
    
    <para>
        The second area of customisation is how <acronym>HMAC</acronym> operates
        when calculating/comparing them for all requests. This is configured using
        the signatureMethod configuration field or <methodname>setSignatureMethod()
        </methodname>. By default this is HMAC-SHA1. You can set it also to a provider's
        preferred method including RSA-SHA1. For RSA-SHA1, you should also configure
        RSA private and public keys via the rsaPrivateKey and rsaPublicKey configuration
        fields or the <methodname>setRsaPrivateKey()</methodname> and
        <nethodname>setRsaPublicKey()</methodname> methods.
    </para>
    
    <para>
        The first part of the OAuth workflow is obtaining a request token. This
        is accomplished using:
    </para>
    
    <programlisting language="php"><![CDATA[
$config = array(
    'callbackUrl' => 'http://example.com/callback.php',
    'siteUrl' => 'http://twitter.com/oauth',
    'consumerKey' => '<KEY>',
    'consumerSecret' => '<KEY>'
);
$consumer = new Zend_Oauth_Consumer($config);

// fetch a request token
$token = $consumer->getRequestToken();
]]></programlisting>

    <para>
        The new request token (an instance of <classname>Zend_Oauth_Token_Request
        </classname>) is unauthorized. In order to exchange it for an authorized
        token with which we can access the Twitter API, we need the user to authorize<commit_msg>[DOCUMENTATION] English: fix compilation error<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.oauth.introduction.getting-started">
    <title>Getting Started</title>

    <para>
        With the OAuth protocol explained, let's show a simple example of it with
        source code. Our new Consumer will be handling Twitter Status submissions.
        To do so, it will need to be registered with Twitter in order to receive
        an OAuth Consumer Key and Consumer Secret. This are utilised to obtain
        an Access Token before we use the Twitter API to post a status message.
    </para>
    
    <para>
        Assuming we have obtained a key and secret, we can start the OAuth workflow
        by setting up a <classname>Zend_Oauth_Consumer</classname> instance as
        follows passing it a configuration (either an array or <classname>
        Zend_Config</classname> object).
    </para>
    
    <programlisting language="php"><![CDATA[
$config = array(
    'callbackUrl' => 'http://example.com/callback.php',
    'siteUrl' => 'http://twitter.com/oauth',
    'consumerKey' => '<KEY>',
    'consumerSecret' => '<KEY>'
);
$consumer = new Zend_Oauth_Consumer($config);
]]></programlisting>

    <para>
        The callbackUrl is the URI we want Twitter to request from our server
        when sending information. We'll look at this later. The siteUrl is the
        base URI of Twitter's OAuth API endpoints. The full list of endpoints include
        http://twitter.com/oauth/request_token, http://twitter.com/oauth/access_token,
        and http://twitter.com/oauth/authorize. The base siteUrl utilises a convention
        which maps to these three OAuth endpoints (as standard) for requesting a
        request token, access token or authorization. If the actual endpoints of
        any service differ from the standard set, these three URIs can be separately
        set using the methods <methodname>setRequestTokenUrl()</methodname>,
        <methodname>setAccessTokenUrl()</methodname>,
        and <methodname>setAuthorizeUrl()</methodname> or the configuration fields requestTokenUrl,
        accessTokenUrl and authorizeUrl.
    </para>
    
    <para>
        The consumerKey and consumerSecret are retrieved from Twitter when your
        application is registered for OAuth access. These also apply to any OAuth
        enabled service, so each one will provide a key and secret for your
        application.
    </para>
    
    <para>
        All of these configuration options may be set using method calls simply
        by converting from, e.g. callbackUrl to setCallbackUrl().
    </para>
    
    <para>
        In addition, you should note several other configuration values not
        explicitly used: requestMethod and requestScheme. By default, <classname>
        Zend_Oauth_Consumer</classname> sends requests as POST (except for a
        redirect which uses GET). The customised client (see later) also includes its
        authorization by way of a header. Some services may, at their discretion,
        require alternatives. You can reset the requestMethod (which defaults
        to Zend_Oauth::POST) to Zend_Oauth::GET, for example, and reset the
        requestScheme from its default of Zend_Oauth::REQUEST_SCHEME_HEADER to one
        of Zend_Oauth::REQUEST_SCHEME_POSTBODY or
        Zend_Oauth::REQUEST_SCHEME_QUERYSTRING. Typically the defaults should work
        fine apart from some exceptional cases. Please refer to the service provider's
        documentation for more details.
    </para>
    
    <para>
        The second area of customisation is how <acronym>HMAC</acronym> operates
        when calculating/comparing them for all requests. This is configured using
        the signatureMethod configuration field or <methodname>setSignatureMethod()
        </methodname>. By default this is HMAC-SHA1. You can set it also to a provider's
        preferred method including RSA-SHA1. For RSA-SHA1, you should also configure
        RSA private and public keys via the rsaPrivateKey and rsaPublicKey configuration
        fields or the <methodname>setRsaPrivateKey()</methodname> and
        <methodname>setRsaPublicKey()</methodname> methods.
    </para>
    
    <para>
        The first part of the OAuth workflow is obtaining a request token. This
        is accomplished using:
    </para>
    
    <programlisting language="php"><![CDATA[
$config = array(
    'callbackUrl' => 'http://example.com/callback.php',
    'siteUrl' => 'http://twitter.com/oauth',
    'consumerKey' => 'gg3DsFTW9OU9eWPnbuPzQ',
    'consumerSecret' => '<KEY>'
);
$consumer = new Zend_Oauth_Consumer($config);

// fetch a request token
$token = $consumer->getRequestToken();
]]></programlisting>

    <para>
        The new request token (an instance of <classname>Zend_Oauth_Token_Request
        </classname>) is unauthorized. In order to exchange it for an authorized
        token with which we can access the Twitter API, we need the user to authorize
{'fraction_non_alphanumeric': 0.07848403461653237, 'fraction_numerical': 0.0019894558838157764, 'mean_word_length': 3.091982091982092, 'pattern_counts': {'":': 0, '<': 109, '<?xml version=': 2, '>': 127, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1115783', 'n_tokens_mistral': 2706, 'n_tokens_neox': 2581, 'n_words': 1073}