README 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. TwitterOAuth
  2. ------------
  3. PHP library for working with Twitter's OAuth API.
  4. Flow Overview
  5. =============
  6. 1. Build TwitterOAuth object using client credentials.
  7. 2. Request temporary credentials from Twitter.
  8. 3. Build authorize URL for Twitter.
  9. 4. Redirect user to authorize URL.
  10. 5. User authorizes access and returns from Twitter.
  11. 6. Rebuild TwitterOAuth object with client credentials and temporary credentials.
  12. 7. Get token credentials from Twitter.
  13. 8. Rebuild TwitterOAuth object with client credentials and token credentials.
  14. 9. Query Twitter API.
  15. Terminology
  16. ===========
  17. The terminology has changed since 0.1.x to better match the draft-hammer-oauth IETF
  18. RFC. You can read that at http://tools.ietf.org/html/draft-hammer-oauth. Some of the
  19. terms will differ from those Twitter uses as well.
  20. client credentials - Consumer key/secret you get when registering an app with Twitter.
  21. temporary credentials - Previously known as the request token.
  22. token credentials - Previously known as the access token.
  23. Parameters
  24. ==========
  25. There are a number of parameters you can modify after creating a TwitterOAuth object.
  26. Switch an existing TwitterOAuth install to use version 1.1 of the API.
  27. $connection->$host = "https://api.twitter.com/1.1/";
  28. Custom useragent.
  29. $connection->useragent = 'Custom useragent string';
  30. Verify Twitters SSL certificate.
  31. $connection->ssl_verifypeer = TRUE;
  32. There are several more you can find in TwitterOAuth.php.
  33. Extended flow using example code
  34. ================================
  35. To use TwitterOAuth with the Twitter API you need *TwitterOAuth.php*, *OAuth.php* and
  36. client credentials. You can get client credentials by registering your application at
  37. [dev.twitter.com/apps](https://dev.twitter.com/apps).
  38. Users start out on connect.php which displays the "Sign in with Twitter" image hyperlinked
  39. to redirect.php. This button should be displayed on your homepage in your login section. The
  40. client credentials are saved in config.php as `CONSUMER_KEY` and `CONSUMER_SECRET`. You can
  41. save a static callback URL in the app settings page, in the config file or use a dynamic
  42. callback URL later in step 2. In example use https://example.com/callback.php.
  43. 1) When a user lands on redirect.php we build a new TwitterOAuth object using the client credentials.
  44. If you have your own configuration method feel free to use it instead of config.php.
  45. $connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET); // Use config.php client credentials
  46. $connection = new TwitterOAuth('abc890', '123xyz');
  47. 2) Using the built $connection object you will ask Twitter for temporary credentials. The `oauth_callback` value is required.
  48. $temporary_credentials = $connection->getRequestToken(OAUTH_CALLBACK); // Use config.php callback URL.
  49. 3) Now that we have temporary credentials the user has to go to Twitter and authorize the app
  50. to access and updates their data. You can also pass a second parameter of FALSE to not use [Sign
  51. in with Twitter](https://dev.twitter.com/docs/auth/sign-twitter).
  52. $redirect_url = $connection->getAuthorizeURL($temporary_credentials); // Use Sign in with Twitter
  53. $redirect_url = $connection->getAuthorizeURL($temporary_credentials, FALSE);
  54. 4) You will now have a Twitter URL that you must send the user to.
  55. https://api.twitter.com/oauth/authenticate?oauth_token=xyz123
  56. 5) The user is now on twitter.com and may have to login. Once authenticated with Twitter they will
  57. will either have to click on allow/deny, or will be automatically redirected back to the callback.
  58. 6) Now that the user has returned to callback.php and allowed access we need to build a new
  59. TwitterOAuth object using the temporary credentials.
  60. $connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $_SESSION['oauth_token'],
  61. $_SESSION['oauth_token_secret']);
  62. 7) Now we ask Twitter for long lasting token credentials. These are specific to the application
  63. and user and will act like password to make future requests. Normally the token credentials would
  64. get saved in your database but for this example we are just using sessions.
  65. $token_credentials = $connection->getAccessToken($_REQUEST['oauth_verifier']);
  66. 8) With the token credentials we build a new TwitterOAuth object.
  67. $connection = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET, $token_credentials['oauth_token'],
  68. $token_credentials['oauth_token_secret']);
  69. 9) And finally we can make requests authenticated as the user. You can GET, POST, and DELETE API
  70. methods. Directly copy the path from the API documentation and add an array of any parameter
  71. you wish to include for the API method such as curser or in_reply_to_status_id.
  72. $account = $connection->get('account/verify_credentials');
  73. $status = $connection->post('statuses/update', array('status' => 'Text of status here', 'in_reply_to_status_id' => 123456));
  74. $status = $connection->delete('statuses/destroy/12345');
  75. Contributors
  76. ============
  77. * [Abraham Williams](https://twitter.com/abraham) - Main developer, current maintainer.