1: <?php
2: namespace Dropbox;
3:
4: /**
5: * Information about how you've registered your application with the Dropbox API.
6: */
7: final class AppInfo
8: {
9: /**
10: * Your Dropbox <em>app key</em> (OAuth calls this the <em>consumer key</em>). You can
11: * create an app key and secret on the <a href="http://dropbox.com/developers/apps">Dropbox developer website</a>.
12: *
13: * @return string
14: */
15: function getKey() { return $this->key; }
16:
17: /** @var string */
18: private $key;
19:
20: /**
21: * Your Dropbox <em>app secret</em> (OAuth calls this the <em>consumer secret</em>). You can
22: * create an app key and secret on the <a href="http://dropbox.com/developers/apps">Dropbox developer website</a>.
23: *
24: * Make sure that this is kept a secret. Someone with your app secret can impesonate your
25: * application. People sometimes ask for help on the Dropbox API forums and
26: * copy/paste code that includes their app secret. Do not do that.
27: *
28: * @return string
29: */
30: function getSecret() { return $this->secret; }
31:
32: /** @var string */
33: private $secret;
34:
35: /**
36: * The type of access your app is registered for. You can see how your apps areregistered
37: * on the <a href="http://dropbox.com/developers/apps">Dropbox developer website</a>.
38: *
39: * @return AccessType
40: */
41: function getAccessType() { return $this->accessType; }
42:
43: /** @var string */
44: private $accessType;
45:
46: /**
47: * The set of servers your app will use. This defaults to the standard Dropbox servers
48: * {@link Host::getDefault}.
49: *
50: * @return Host
51: *
52: * @internal
53: */
54: function getHost() { return $this->host; }
55:
56: /** @var Host */
57: private $host;
58:
59: /**
60: * Constructor.
61: *
62: * @param string $key
63: * See {@link getKey()}
64: * @param string $secret
65: * See {@link getSecret()}
66: * @param string $accessType
67: * See {@link getAccessType()}
68: */
69: function __construct($key, $secret, $accessType)
70: {
71: Token::checkKeyArg($key);
72: Token::checkSecretArg($secret);
73: AccessType::checkArg("accessType", $accessType);
74:
75: $this->key = $key;
76: $this->secret = $secret;
77: $this->accessType = $accessType;
78:
79: // The $host parameter is sort of internal. We don't include it in the param list because
80: // we don't want it to be included in the documentation. Use PHP arg list hacks to get at
81: // it.
82: $host = null;
83: if (\func_num_args() == 4) {
84: $host = \func_get_arg(3);
85: Host::checkArgOrNull("host", $host);
86: }
87: if ($host === null) {
88: $host = Host::getDefault();
89: }
90: $this->host = $host;
91: }
92:
93: /**
94: * Loads a JSON file containing information about your app. At a minimum, the file must include
95: * the key, secret, and access_type fields. Run 'php authorize.php' in the examples directory
96: * for details about what this file should look like.
97: *
98: * @param string $path Path to a JSON file
99: * @return AppInfo
100: */
101: static function loadFromJsonFile($path)
102: {
103: list($rawJson, $appInfo) = self::loadFromJsonFileWithRaw($path);
104: return $appInfo;
105: }
106:
107: /**
108: * Loads a JSON file containing information about your app. At a minimum, the file must include
109: * the key, secret, and access_type fields. Run 'php authorize.php' in the examples directory
110: * for details about what this file should look like.
111: *
112: * @param string $path Path to a JSON file
113: *
114: * @return array
115: * A list of two items. The first is a PHP array representation of the raw JSON, the second
116: * is an AppInfo object that is the parsed version of the JSON.
117: *
118: * @internal
119: */
120: static function loadFromJsonFileWithRaw($path)
121: {
122: if (!file_exists($path)) {
123: throw new AppInfoLoadException("File doesn't exist: \"$path\"");
124: }
125:
126: $str = file_get_contents($path);
127: $jsonArr = json_decode($str, TRUE);
128:
129: if (is_null($jsonArr)) {
130: throw new AppInfoLoadException("JSON parse error: \"$path\"");
131: }
132:
133: $appInfo = self::loadFromJson($jsonArr);
134:
135: return array($jsonArr, $appInfo);
136: }
137:
138: /**
139: * Parses a JSON object to build an AppInfo object. If you would like to load this from a file,
140: * use the loadFromJsonFile() method.
141: *
142: * @param array $jsonArr Output from json_decode($str, TRUE)
143: *
144: * @return AppInfo
145: *
146: * @throws AppInfoLoadException
147: */
148: static function loadFromJson($jsonArr)
149: {
150: if (!is_array($jsonArr)) {
151: throw new AppInfoLoadException("Expecting JSON object, got something else");
152: }
153:
154: $requiredKeys = array("key", "secret", "access_type");
155: foreach ($requiredKeys as $key) {
156: if (!isset($jsonArr[$key])) {
157: throw new AppInfoLoadException("Missing field \"$key\"");
158: }
159:
160: if (!is_string($jsonArr[$key])) {
161: throw new AppInfoLoadException("Expecting field \"$key\" to be a string");
162: }
163: }
164:
165: // Check app_key and app_secret
166: $appKey = $jsonArr["key"];
167: $appSecret = $jsonArr["secret"];
168:
169: $tokenErr = Token::getTokenPartError($appKey);
170: if (!is_null($tokenErr)) {
171: throw new AppInfoLoadException("Field \"key\" doesn't look like a valid app key: $tokenErr");
172: }
173:
174: $tokenErr = Token::getTokenPartError($appSecret);
175: if (!is_null($tokenErr)) {
176: throw new AppInfoLoadException("Field \"secret\" doesn't look like a valid app secret: $tokenErr");
177: }
178:
179: // Check the access type
180: $accessTypeStr = $jsonArr["access_type"];
181: if ($accessTypeStr === "FullDropbox") {
182: $accessType = AccessType::FullDropbox();
183: }
184: else if ($accessTypeStr === "AppFolder") {
185: $accessType = AccessType::AppFolder();
186: }
187: else {
188: throw new AppInfoLoadException("Field \"access_type\" must be either \"FullDropbox\" or \"AppFolder\"");
189: }
190:
191: // Check for the optional 'host' field
192: if (!isset($jsonArr["host"])) {
193: $host = Host::getDefault();
194: }
195: else {
196: $baseHost = $jsonArr["host"];
197: if (!is_string($baseHost)) {
198: throw new AppInfoLoadException("Optional field \"host\" must be a string");
199: }
200:
201: $api = "api-$baseHost";
202: $content = "api-content-$baseHost";
203: $web = "meta-$baseHost";
204:
205: $host = new Host($api, $content, $web);
206: }
207:
208: return new AppInfo($appKey, $appSecret, $accessType, $host);
209: }
210:
211: /**
212: * Use this to check that a function argument is of type <code>AppInfo</code>
213: *
214: * @internal
215: */
216: static function checkArg($argName, $argValue)
217: {
218: if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
219: }
220:
221: /**
222: * Use this to check that a function argument is either <code>null</code> or of type
223: * <code>AppInfo</code>.
224: *
225: * @internal
226: */
227: static function checkArgOrNull($argName, $argValue)
228: {
229: if ($argValue === null) return;
230: if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
231: }
232: }
233: