1: <?php
 2: namespace Dropbox;
 3: 
 4: /**
 5:  * A request token is used during the three-step OAuth web flow to identify the authorization
 6:  * session.  Once authorization is complete and you have an access token, you don't need
 7:  * the request token anymore.
 8:  *
 9:  * Storing Request Tokens
10:  *
11:  * If you are doing the three-step OAuth web flow in a web application, it'll probably
12:  * span two separate HTTP requests to your app.  In the first request you'll call
13:  * {@link WebAuth::start()} and get a request token.  You need to store that request
14:  * token somewhere (browser cookie, server-side session, database, etc.) so that you can
15:  * pass it to {@link WebAuth::finish()} later.
16:  *
17:  * You can convert this object into a single string using {@link RequestToken::serialize()},
18:  * and use {@link RequestToken::parse()} to convert that string back into an object.
19:  */
20: final class RequestToken extends Token
21: {
22:     /**
23:      * Tacked on to the front of the serialized string to distinguish it from other token types.
24:      *
25:      * @var string
26:      */
27:     private static $TypeTag = "r|";
28: 
29:     /**
30:      * @internal
31:      *
32:      * @param string $key
33:      * @param string $value
34:      */
35:     function __construct($key, $value)
36:     {
37:         parent::__construct($key, $value);
38:     }
39: 
40:     /**
41:      * Returns a string representation of this request token.  Can be convenient when
42:      * storing the access token to a file or database.
43:      *
44:      * @return string
45:      */
46:     function serialize()
47:     {
48:         return $this->serializeWithTag(self::$TypeTag);
49:     }
50: 
51:     /**
52:      * Convert a string generated by {@link serialize()} back into a {@link RequestToken}
53:      * object.
54:      *
55:      * @param string $data
56:      * @return RequestToken
57:      * @throws DeserializeException
58:      */
59:     static function deserialize($data)
60:     {
61:         $parts = parent::deserializeWithTag(self::$TypeTag, $data);
62:         return new RequestToken($parts[0], $parts[1]);
63:     }
64: 
65:     /**
66:      * Check that a function argument is of type <code>RequestToken</code>.
67:      *
68:      * @internal
69:      */
70:     static function checkArg($argName, $argValue)
71:     {
72:         if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
73:     }
74: 
75:     /**
76:      * Check that a function argument is either <code>null</code> or of type
77:      * <code>RequestToken</code>.
78:      *
79:      * @internal
80:      */
81:     static function checkArgOrNull($argName, $argValue)
82:     {
83:         if ($argValue === null) return;
84:         if (!($argValue instanceof self)) Checker::throwError($argName, $argValue, __CLASS__);
85:     }
86: }
87: