Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added documentation wih new terminology

  • Loading branch information...
commit 8da02a678b9c408eb8ca1ffd9c38323f2da632a5 1 parent e161de3
@abraham abraham authored
Showing with 120 additions and 1 deletion.
  1. +120 −1 DOCUMENTATION
View
121 DOCUMENTATION
@@ -1 +1,120 @@
-Coming soon...
+TwitterOAuth documentation.
+
+
+
+GET THE CODE
+====================
+You can pull the latest development version using git:
+git clone git://github.com/abraham/twitteroauth.git
+
+Or you can download the latest release by visiting:
+http://github.com/abraham/twitteroauth/downloads
+
+
+FLOW OVERVIEW
+====================
+1) Build TwitterOAuth object using client credentials.
+2) Request temporary credentials from Twitter.
+3) Build authorize URL for Twitter.
+4) Redirect user to authorize URL.
+5) User authorizes access and returns from Twitter.
+6) Rebuild TwitterOAuth object with client credentials and temporary credentials.
+7) Get token credentials from Twitter.
+8) Rebuild TwitterOAuth object with client credentials and token credentials.
+9) Query Twitter API.
+
+
+TERMINOLOGY
+====================
+The terminology has changed since 0.1.x to better match the draft-hammer-oauth IETF
+RFC. You can read that at http://tools.ietf.org/html/draft-hammer-oauth. Some of the
+terms will differ from those Twitter uses as well.
+
+client credentials - Consumer key/secret you get when registering an app with Twitter.
+temporary credentials - Previously known as the request token.
+token credentials - Previously known as the access token.
+
+
+PARAMETERS
+====================
+There are a number of parameters you can modify after creating a TwitterOAuth object.
+
+Switch to XML instead of JSON.
+$connection->format = 'xml';
+
+Stop auto decoding JSON.
+$connection->decode_json = FALSE;
+
+Custom useragent.
+$connection->useragent = 'Custom useragent string';
+
+Verify Twitters SSL certificate.
+$connection->ssl_verifypeer = TRUE;
+
+There are several more you can find in TwitterOAuth.php.
+
+
+
+EXTENDED FLOW USING EXAMPLE CODE
+====================
+To use TwitterOAuth with the Twitter API you need TwitterOAuth.php, OAuth.php and
+client credentials. You can get client credentials by registering your application at
+https://twitter.com/apps.
+
+The example files are explained below.
+
+0) Users start out on connect.php which displays the "Sign in with Twitter" image hyperlinked
+to redirect.php. This button should be displayed on your homepage in your login section. The
+client credentials are saved in config.php as CONSUMER_KEY and CONSUMER_SECRET. You can
+save a static callback URL in the app settings page, in the config file or use a dynamic
+callback URL later in step 2. In example use http://example.com/callback.php.
+
+1) When a user lands on redirect.php we build a new TwitterOAuth object using the client
+credentials. If you have your own configuration method feel free to use it instead of config.php.
+$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET);// Use config.php client credentials
+$connection = new TwitterOAuth('abc890', '123xyz');
+
+2) Using the built $connection object you will ask Twitter for temporary credentials. If you
+wish to have a dynamic callback URL for each user you can do pass a URL as a parameter.
+$temporary_credentials = $connection->getRequestToken(); // Use applications registered callback.
+$temporary_credentials = $connection->getRequestToken('http://example.com/callback.php?');
+
+3) Now that we have temporary credentials the user has to go to Twitter and authorize the app
+to access and updates their data. You can also pass a second parameter of FALSE to not use Sign
+in with Twitter: http://apiwiki.twitter.com/Sign-in-with-Twitter.
+$redirect_url = $connection->getAuthorizeURL($temporary_credentials); // Use Sign in with Twitter
+$redirect_url = $connection->getAuthorizeURL($temporary_credentials, FALSE);
+
+4) You will now have a Twitter URL that you must send the user to. You can add parameters and
+they will return with the user in step 5.
+https://twitter.com/oauth/authenticate?oauth_token=xyz123
+https://twitter.com/oauth/authenticate?oauth_token=xyz123&info=abc // info will return with user
+
+5) The user is now on twitter.com and may have to login. Once authenticated with Twitter they will
+will either have to click on allow/deny, or will be automatically redirected back to the callback.
+
+6) Now that the user has returned to callback.php and allowed access we need to build a new
+TwitterOAuth object using the temporary credentials.
+$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $_SESSION['oauth_token'],
+$_SESSION['oauth_token_secret']);
+
+7) Now we ask Twitter for long lasting token credentials. These are specific to the application
+and user and will act like password to make future requests. If a dynamic callback URL was used
+you will also have to pass the oauth_varifier parameter. Normally the token credentials would
+get saved in your database but for this example we are just using sessions.
+$token_credentials = $connection->getAccessToken(); // Used applications registered callback URL
+$token_credentials = $connection->getAccessToken($_REQUEST['oauth_verifier']);
+
+7a) After getting the token credentials we redirect the user to index.php.
+
+8) With the token credentials we build a new TwitterOAuth object.
+$connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $token_credentials['oauth_token'],
+$token_credentials['oauth_token_secret']);
+
+9) And finally we can make requests authenticated as the user. You can GET, POST, and DELETE API
+methods. Directly copy the path from the API documentation and add an array of any parameter
+you wish to include for the API method such as curser or in_reply_to_status_id.
+$content = $connection->get('account/verify_credentials');
+$connection->post('statuses/update', array('status' => 'Text of status here',
+'in_reply_to_status_id' => 123456));
+$content = $connection->delete('statuses/destroy/12345');
Please sign in to comment.
Something went wrong with that request. Please try again.