1:  2:  3:  4:  5:  6:  7:  8:  9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 

<?php
namespace Dropbox;

/**
 * OAuth 2 code-based authorization for apps that can't provide a redirect URI, typically
 * command-line example apps.
 *
 * Use {@link start()} and {@link getToken()} to guide your
 * user through the process of giving your app access to their Dropbox account.  At the end, you
 * will have an {@link AccessToken}, which you can pass to {@link Client} and start making
 * API calls.
 *
 * Example:
 *
 * <code>
 * use \Dropbox as dbx;
 * $appInfo = dbx\AppInfo::loadFromJsonFile(...);
 * $clientIdentifier = "my-app/1.0";
 * $webAuth = new dbx\WebAuthNoRedirect($appInfo, $clientIdentifier, ...);
 *
 * $authorizeUrl = $webAuth->start();
 *
 * print("1. Go to: $authorizeUrl\n");
 * print("2. Click "Allow" (you might have to log in first).\n");
 * print("3. Copy the authorization code.\n");
 * print("Enter the authorization code here: ");
 * $code = \trim(\fgets(STDIN));
 *
 * try {
 *    list($accessToken, $userId) = $webAuth->finish($code);
 * }
 * catch (dbx\Exception $ex) {
 *    print("Error communicating with Dropbox API: " . $ex->getMessage() . "\n");
 * }
 *
 * $client = dbx\Client($accessToken, $clientIdentifier, ...);
 * </code>
 */
class WebAuthNoRedirect extends WebAuthBase
{
    /**
     * Returns the URL of the authorization page the user must visit.  If the user approves
     * your app, they will be shown the authorization code on the web page.  They will need to
     * copy/paste that code into your application so your app can pass it to
     * {@link finish}.
     *
     * See <a href="https://www.dropbox.com/developers/core/docs#oa2-authorize">/oauth2/authorize</a>.
     *
     * @return string
     *    An authorization URL.  Direct the user's browser to this URL.  After the user decides
     *    whether to authorize your app or not, Dropbox will show the user an authorization code,
     *    which the user will need to give to your application (e.g. via copy/paste).
     */
    function start()
    {
        return $this->_getAuthorizeUrl(null, null);
    }

    /**
     * Call this after the user has visited the authorize URL returned by {@link start()},
     * approved your app, was presented with an authorization code by Dropbox, and has copy/paste'd
     * that authorization code into your app.
     *
     * See <a href="https://www.dropbox.com/developers/core/docs#oa2-token">/oauth2/token</a>.
     *
     * @param string $code
     *    The authorization code provided to the user by Dropbox.
     *
     * @return array
     *    A `list(string $accessToken, string $userId)`, where
     *    `$accessToken` can be used to construct a {@link Client} and
     *    `$userId` is the user ID of the user's Dropbox account.
     *
     * @throws Exception
     *    Thrown if there's an error getting the access token from Dropbox.
     */
    function finish($code)
    {
        Checker::argStringNonEmpty("code", $code);
        return $this->_finish($code, null);
    }
}