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:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 

<?php
namespace Dropbox;

/**
 * Your app's API key and secret.
 */
final class AppInfo
{
    /**
     * Your Dropbox <em>app key</em> (OAuth calls this the <em>consumer key</em>).  You can
     * create an app key and secret on the <a href="http://dropbox.com/developers/apps">Dropbox developer website</a>.
     *
     * @return string
     */
    function getKey() { return $this->key; }

    /** @var string */
    private $key;

    /**
     * Your Dropbox <em>app secret</em> (OAuth calls this the <em>consumer secret</em>).  You can
     * create an app key and secret on the <a href="http://dropbox.com/developers/apps">Dropbox developer website</a>.
     *
     * Make sure that this is kept a secret.  Someone with your app secret can impesonate your
     * application.  People sometimes ask for help on the Dropbox API forums and
     * copy/paste code that includes their app secret.  Do not do that.
     *
     * @return string
     */
    function getSecret() { return $this->secret; }

    /** @var string */
    private $secret;

    /**
     * The set of servers your app will use.  This defaults to the standard Dropbox servers
     * {@link Host::getDefault}.
     *
     * @return Host
     *
     * @internal
     */
    function getHost() { return $this->host; }

    /** @var Host */
    private $host;

    /**
     * Constructor.
     *
     * @param string $key
     *    See {@link getKey()}
     * @param string $secret
     *    See {@link getSecret()}
     */
    function __construct($key, $secret)
    {
        self::checkKeyArg($key);
        self::checkSecretArg($secret);

        $this->key = $key;
        $this->secret = $secret;

        // The $host parameter is sort of internal.  We don't include it in the param list because
        // we don't want it to be included in the documentation.  Use PHP arg list hacks to get at
        // it.
        $host = null;
        if (\func_num_args() == 3) {
            $host = \func_get_arg(2);
            Host::checkArgOrNull("host", $host);
        }
        if ($host === null) {
            $host = Host::getDefault();
        }
        $this->host = $host;
    }

    /**
     * Loads a JSON file containing information about your app. At a minimum, the file must include
     * the "key" and "secret" fields.  Run 'php authorize.php' in the examples directory
     * for details about what this file should look like.
     *
     * @param string $path
     *    Path to a JSON file
     *
     * @return AppInfo
     *
     * @throws AppInfoLoadException
     */
    static function loadFromJsonFile($path)
    {
        list($rawJson, $appInfo) = self::loadFromJsonFileWithRaw($path);
        return $appInfo;
    }

    /**
     * Loads a JSON file containing information about your app. At a minimum, the file must include
     * the "key" and "secret" fields.  Run 'php authorize.php' in the examples directory
     * for details about what this file should look like.
     *
     * @param string $path
     *    Path to a JSON file
     *
     * @return array
     *    A list of two items.  The first is a PHP array representation of the raw JSON, the second
     *    is an AppInfo object that is the parsed version of the JSON.
     *
     * @throws AppInfoLoadException
     *
     * @internal
     */
    static function loadFromJsonFileWithRaw($path)
    {
        if (!file_exists($path)) {
            throw new AppInfoLoadException("File doesn't exist: \"$path\"");
        }

        $str = Util::stripUtf8Bom(file_get_contents($path));
        $jsonArr = json_decode($str, true, 10);

        if (is_null($jsonArr)) {
            throw new AppInfoLoadException("JSON parse error: \"$path\"");
        }

        $appInfo = self::loadFromJson($jsonArr);

        return array($jsonArr, $appInfo);
    }

    /**
     * Parses a JSON object to build an AppInfo object.  If you would like to load this from a file,
     * use the loadFromJsonFile() method.
     *
     * @param array $jsonArr Output from json_decode($str, true)
     *
     * @return AppInfo
     *
     * @throws AppInfoLoadException
     */
    static function loadFromJson($jsonArr)
    {
        if (!is_array($jsonArr)) {
            throw new AppInfoLoadException("Expecting JSON object, got something else");
        }

        $requiredKeys = array("key", "secret");
        foreach ($requiredKeys as $key) {
            if (!array_key_exists($key, $jsonArr)) {
                throw new AppInfoLoadException("Missing field \"$key\"");
            }

            if (!is_string($jsonArr[$key])) {
                throw new AppInfoLoadException("Expecting field \"$key\" to be a string");
            }
        }

        // Check app_key and app_secret
        $appKey = $jsonArr["key"];
        $appSecret = $jsonArr["secret"];

        $tokenErr = self::getTokenPartError($appKey);
        if (!is_null($tokenErr)) {
            throw new AppInfoLoadException("Field \"key\" doesn't look like a valid app key: $tokenErr");
        }

        $tokenErr = self::getTokenPartError($appSecret);
        if (!is_null($tokenErr)) {
            throw new AppInfoLoadException("Field \"secret\" doesn't look like a valid app secret: $tokenErr");
        }

        try {
            $host = Host::loadFromJson($jsonArr);
        }
        catch (HostLoadException $ex) {
            throw new AppInfoLoadException($ex->getMessage());
        }

        return new AppInfo($appKey, $appSecret, $host);
    }

    /**
     * Use this to check that a function argument is of type `AppInfo`
     *
     * @internal
     */
    static function checkArg($argName, $argValue)
    {
        if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
    }

    /**
     * Use this to check that a function argument is either `null` or of type
     * `AppInfo`.
     *
     * @internal
     */
    static function checkArgOrNull($argName, $argValue)
    {
        if ($argValue === null) return;
        if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
    }

    /** @internal */
    static function getTokenPartError($s)
    {
        if ($s === null) return "can't be null";
        if (strlen($s) === 0) return "can't be empty";
        if (strstr($s, ' ')) return "can't contain a space";
        return null;  // 'null' means "no error"
    }

    /** @internal */
    static function checkKeyArg($key)
    {
        $error = self::getTokenPartError($key);
        if ($error === null) return;
        throw new \InvalidArgumentException("Bad 'key': \"$key\": $error.");
    }

    /** @internal */
    static function checkSecretArg($secret)
    {
        $error = self::getTokenPartError($secret);
        if ($error === null) return;
        throw new \InvalidArgumentException("Bad 'secret': \"$secret\": $error.");
    }

}