Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 164 lines (125 sloc) 6.077 kB
6986981 @michaelcurtis Refactored to separate app-specific cookie logic from the core library.
authored
1 # Overview
2
3 YmailPHP is a PHP client library for the [Yahoo Mail web service](http://developer.yahoo.com/mail/).
4 The client supports the OAuth authorization model and the JSON variant of the API.
5
6 To get an OAuth key that works for Yahoo Mail visit the [YDN OAuth page](http://developer.yahoo.com/oauth/).
7
8 Also, you can read [this getting started tutorial]() which guides you through acquiring an
9 OAuth key and using the YmailPHP library.
10
11 # Using the library
12
13 YmailPHP is a Yahoo Mail web service client library. To use it you construct a `YMClient`
14 instance and make subsequent method calls that mirror the web service APIs. The following
15 code snippet will construct a `YMClient` and use it to print the folder list for a mailbox.
16
17 <?php
d4da24a @michaelcurtis renamed ymclient.inc to ymclient.php
authored
18 require_once 'ymclient.php';
6986981 @michaelcurtis Refactored to separate app-specific cookie logic from the core library.
authored
19
20 $ymc = new YMClient(
21 OAUTH_CONSUMER_KEY,
22 OAUTH_CONSUMER_SECRET
23 );
24
25 $oaToken = new OAuthToken(
26 OAUTH_TOKEN,
27 OAUTH_TOKEN_SECRET
28 );
29
30 try {
31 print_r($ymc->ListFolders(new stdclass(), $oaToken));
32 }
33
34 catch(YMClientException $e) {
35 // Uh oh...
36 }
37 ?>
38
39 The `OAuthToken` must be an access token, not a request token. If the access token is stale
40 then the YmailPHP library will attempt to refresh it.
41
42 The YmailPHP library provides some functions that make it easier to create and
43 manage OAuth sessions with the Ymail web service. The following methods are available
44 in the `YMClient` class:
45
46 * `oauth_get_request_token()`
47 * `oauth_get_access_token()`
48 * `oauth_get_refreshed_token()` - returns an OAuthToken if it was refreshed by the previous call
49
50 In addition, it provides some methods to (de-)serialize OAuth tokens to and
51 from query strings. These query strings are compatible with those generated by
52 `OAuthToken.from_string()`, but contain additional data that allows for token refresh, etc.
53
54 * `oauth_token_to_query_string()`
55 * `oauth_token_from_query_string()`
8660b1b @michaelcurtis Refactored to separate app-specific cookie logic from the core library.
authored
56
57 # Complete example
58
59 Here is a complete working example. It will fetch the list of folders from a mailbox along
60 with information about the first ten messages. Set your own consumer key, secret and callback
61 url constants to try it out.
62
63 <?php
d4da24a @michaelcurtis renamed ymclient.inc to ymclient.php
authored
64 require_once 'ymclient.php';
8660b1b @michaelcurtis Refactored to separate app-specific cookie logic from the core library.
authored
65
66 define(OA_CONSUMER_KEY, "...");
67 define(OA_CONSUMER_SECRET, "...");
68 define(OA_CALLBACK_URL, "...");
69
70 define('REQUEST_TOKEN_COOKIE_NAME', 'rt');
71 define('ACCESS_TOKEN_COOKIE_NAME', 'at');
72
73 $ymc = new YMClientRequest(OA_CONSUMER_KEY, OA_CONSUMER_SECRET, OA_CALLBACK_URL);
74
75 try {
76 header("Content-type: application/json\r\n\r\n");
77
78 $folders = $ymc->ListFolders(new stdclass());
79
80 $req = new stdclass();
81 $req->fid = "Inbox";
82 $req->startInfo = 0;
83 $req->numInfo = 10;
84 $messages = $ymc->ListMessages($req);
85
86 print json_encode(array($folders, $messages));
87 }
88
89 catch(YMClientException $e) {
90 header("Content-type: text/plain\r\n\r\n");
91 print_r($e);
92 }
93
94 /**
95 * A wrapper class that manages OAuth sessions in cookies for
96 * this application. It could be modified to store sessions
97 * along with access tokens in a database.
98 */
99 class YMClientRequest {
100 function __construct($oaConsumerKey, $oaConsumerSecret, $callbackURL) {
101 $this->oaConsumerKey = $oaConsumerKey;
102 $this->oaConsumerSecret = $oaConsumerSecret;
103 $this->callbackURL = $callbackURL;
104 $this->ymc = new YMClient($oaConsumerKey, $oaConsumerSecret);
105 }
106
107 function __call($method, $arguments) {
108 $tok = $this->__get_access_token();
109 $result = $this->ymc->$method($arguments, $tok);
110 $newtok = $this->ymc->oauth_get_refreshed_token();
111 if($newtok) {
112 setcookie(ACCESS_TOKEN_COOKIE_NAME,
113 YMClient::oauth_token_to_query_string($newtok));
114 }
115
116 return $result;
117 }
118
119 /**
120 * This method attempts to get an access token from the cookie. If
121 * that fails it checks if this is a callback request from app
122 * authentication and if so requests a new access token. Otherwise
123 * the user hasn't granted the application access yet and it
124 * redirects them to the Yahoo login page to do so.
125 */
126 private function __get_access_token() {
127 // Access token exists in a cookie
128 if($_COOKIE[ACCESS_TOKEN_COOKIE_NAME]) {
129 parse_str($_COOKIE[ACCESS_TOKEN_COOKIE_NAME], $tok);
130 return $tok;
131 }
132
133 // Handling a redirect back from login
134 else if($_COOKIE[REQUEST_TOKEN_COOKIE_NAME] && $_REQUEST['oauth_verifier'] && $_REQUEST['oauth_token']) {
135 $tok = YMClient::oauth_token_from_query_string($_COOKIE[REQUEST_TOKEN_COOKIE_NAME]);
136
137 if($tok['oauth_token'] != $_REQUEST['oauth_token']) {
138 throw new Exception("Cookie and URL disagree about request token value");
139 }
140
141 $tok['oauth_verifier'] = $_REQUEST['oauth_verifier'];
142 $newtok = $this->ymc->oauth_get_access_token($tok);
143
144 setcookie(REQUEST_TOKEN_COOKIE_NAME, "", time()-3600);
145 setcookie(ACCESS_TOKEN_COOKIE_NAME, YMClient::oauth_token_to_query_string($newtok));
146 return $newtok;
147 }
148
149 // Sending the user to login to grant access to this app
150 else {
151 list ($tok, $url) = $this->ymc->oauth_get_request_token($this->callbackURL);
152 setcookie(REQUEST_TOKEN_COOKIE_NAME, YMClient::oauth_token_to_query_string($tok));
153 header("Location: $url");
154 }
155 }
156 }
157 ?>
8626159 @michaelcurtis Added attribution for Peter and PyCascade
authored
158
159 # Notes
160
161 Authored by Mike Curtis - [http://twitter.com/mikecurtis](http://twitter.com/mikecurtis)
162
163 Mostly a port of [PyCascade](http://github.com/pgriess/PyCascade) by [Peter Griess](http://github.com/pgriess)
Something went wrong with that request. Please try again.