1# tmhOAuth 2 3An OAuth 1.0A library written in PHP by @themattharris, specifically for use 4with the Twitter API. 5 6**Disclaimer**: This project is a work in progress. Please use the issue tracker 7to report any enhancements or issues you encounter. 8 9## Goals 10 11- Support OAuth 1.0A 12- Use Authorisation headers instead of query string or POST parameters 13- Allow uploading of images 14- Provide enough information to assist with debugging 15 16## Dependencies 17 18The library has been tested with PHP 5.3+ and relies on CURL and hash_hmac. The 19vast majority of hosting providers include these libraries and run with PHP 5.1+. 20 21The code makes use of hash_hmac, which was introduced in PHP 5.1.2. If your version 22of PHP is lower than this you should ask your hosting provider for an update. 23 24## A note about security and SSL 25 26Version 0.60 hardened the security of the library and defaulted `curl_ssl_verifypeer` to `true`. 27As some hosting providers do not provide the most current certificate root file 28it is now included in this repository. If the version is out of date OR you prefer 29to download the certificate roots yourself, you can get them 30from: http://curl.haxx.se/ca/cacert.pem 31 32Before upgrading the version of tmhOAuth that you use, be sure to verify the SSL 33handling works on your server by running the `examples/verify_ssl.php` script. 34 35## Usage 36 37This will be built out later but for the moment review the examples repository 38<https://github.com/themattharris/tmhOAuth-examples> for ways the library can be 39used. Each example contains instructions on how to use it. 40 41## Notes for users of previous versions 42 43If you previously used version 0.4 be aware the utility functions 44have now been broken into their own file. Before you use version 0.5+ in your app 45test locally to ensure your code doesn't need tmhUtilities included. 46 47If you used custom HTTP request headers when they were defined as `'key: value'` strings 48you should now define them as `'key' => 'value'` pairs. 49 50Versions prior to 0.7.3 collapsed headers with the same value into one 51$tmhOAuth->response['headers'] key. Since 0.7.3 headers with the same key will use an array 52to store their values. 53 54## Change History 55### 0.7.5 - 20 Februrary 2013 56- tidying up of composer.json. (Issue #112) Props: ceeram 57 58### 0.7.4 - 19 Februrary 2013 59- corrections to composer.json to support packagists requirements. (Issue #110) 60 61### 0.7.3 - 18 Februrary 2013 62- add support for making requests with the host header being different to the request host. 63- ensure headers with the same key do not overwrite each other in $tmhOAuth->response['headers']. 64- removed examples submodule in favor of examples including tmhOAuth, rather than tmhOAuth including examples 65- made it so that if param values are sent to $tmhOAuth->request as an array (key -> array()) then $tmhOAuth->prepare_params will now implode them using ',' 66- fixed composer. (Issue #99). Props: rasa 67- fixed PHPDoc. (Issue #47). Props: trante 68- instead of void, $tmhOAuth->curlit now returns 0 if 'prevent_request' is set 69 70### 0.7.2 - 01 November 2012 71- use DIRECTORY_SEPARATOR for multi-environment support. (Issue #80) Props: whallz 72- tidied up the curlHeader function to use explode instead of substr and store the keys in the format they are returned from the API 73- removed content-length hack as it isn't needed if CURLOPT_POSTFIELDS is initialized on all POSTs 74- removed the expects header hack as Twitter no longer requires it to be there 75- introduce composer.json. (Issues #39, #77, #85) Props: akandels, conradkleinespel, dguyon, kud, philsturgeon, willdurand 76- added support for specifying custom headers when using $tmhOAuth->request. (Issue #98) 77 78### 0.7.1 - 27 October 2012 79- set content-length to 0 explictly to avoid a bug between libcurl and Twitter. (Issue #94) 80- allow initialization without a configuration array (default config to array()) 81- prevent ->url allowing double slashes in paths 82 83### 0.7.0 - 04 September 2012 84- changed version numbers to x.y.z format 85- stronger method scoping (public and private) 86- Typo fix in depenencies. (Issue #42) Props: tantek 87- Only lowercase the host and scheme, and not path, in prepare_url. (Issue #56) Props: uzyn 88- Fixed a number of PHP warnings by changing some tmhUtilty methods to static. (Issue #52) Props: DrayChou 89- Raw headers and response body are now available as `$tmhOAuth->response['raw']` 90- Moved the examples to their own repository <https://github.com/themattharris/tmhOAuth-examples> 91- Removed the `noexamples` branch as master does not contain examples anymore 92- Introduced `$tmhOAuth->config['timezone']` and set `date_default_timezone_set`. (Issue #70) Props: iamctodd 93 94### 0.621 - 12 March 2012 95- Ensure `$_SERVER['HTTPS']` isset before checking it's value. Props: kud 96 97### 0.62 - 01 March 2012 98- Fix array merging bug. Props: julien-c 99- use is_callable instead of function_exists: Props: samwierema 100- Allow options to be specified for the entify function. Props: davidcroda 101- protocol was not inferred correctly for https when ['HTTPS'] == 'on'. Props: ospector 102- Switched to https for twitter.com display URLs 103- Improved the search results example 104 105### 0.61 - 16 January 2012 106- Removed trailing ?> from tmhOAuth.php and tmhUtilities.php to meet the Zend Framework's coding practices. Props: reedy 107- Fixed bug where CURLOPT_SSL_VERIFYHOST was defaulted to true when it should have been defaulted to 2. Props: kevinsmcarthur 108 109### 0.60 - 29 December 2011 110- Changed any use of implode to the preferred format of implode($glue, $pieces). Props: reedy 111- Moved oauth_verifier to the authorization header as shown in example of RFC 5849. Props: spacenick 112- added curl error and error number values to the $tmhOAuth->response object 113- added an example script for testing the SSL connection to twitter.com with the new SSL configuration of tmhOAuth 114- added a function to generate the useragent depending on whether SSL is on or not 115- defaulted CURLOPT_SSL_VERIFYPEER to true 116- added CURLOPT_SSL_VERIFYHOST and defaulted it to true 117- added the most current cacert.pem file from http://curl.haxx.se/ca/cacert.pem and configured curl to use it 118 119### 0.58 - 29 December 2011 120- Rearranged some configuration variables around to make commenting easier 121- Standarised on lowercase booleans 122 123### 0.57 - 11 December 2011 124- Fixed prevent_request so OAuth Echo requests work again. 125- Added a TwitPic OAuth Echo example 126 127### 0.56 - 29 September 2011 128- Fixed version reference in the UserAgent 129- Updated tmhUtilities::entify with support for media 130- Updated tmhUtilities::entify with support for multibyte characters. Props: andersonshatch 131 132### 0.55 - 29 September 2011 133- Added support for content encoding. Defaults to whatever localhost supports. Props: yusuke 134 135### 0.54 - 29 September 2011 136- User-Agent is now configurable and includes the current version number of the script 137- Updated the Streaming examples to use SSL 138 139### 0.53 - 15 July 2011 140- Fixed issue where headers were being duplicated if the library was called more than once. 141- Updated examples to fit the new location of access tokens and secrets on dev.twitter.com 142- Added Photo Tweet example 143 144### 0.52 - 06 July 2011 145- Fixed issue where the preference for include_time in create_nonce was being ignored 146 147### 0.51 - 06 July 2011 148- Use isset instead of suppress errors. Props: funkatron 149- Added example of using the Search API 150- Added example of using friends/ids and users/lookup to get details of a users friends 151- Added example of the authorize OAuth webflow 152 153### 0.5 - 29 March 2011 154- Moved utility functions out of the main class and into the tmhUtilities class. 155- Added the ability to send OAuth parameters as part of the querystring or POST body. 156- Section 3.4.1.2 says the url must be lowercase so prepare URL now does this. 157- Added a convenience method for accessing the safe_encode/decode transforms. 158- Updated the examples to use the new utilities library. 159- Added examples for sitestreams and userstreams. 160- Added a more advanced streaming API example. 161 162### 0.4 - 03 March 2011 163- Fixed handling of parameters when using DELETE. Thanks to yusuke for reporting 164- Fixed php_self to handle port numbers other than 80/443. Props: yusuke 165- Updated function pr to use pre only when not running in CLI mode 166- Add support for proxy servers. Props juanchorossi 167- Function request now returns the HTTP status code. Props: kronenthaler 168- Documentation fixes for xAuth. Props: 140dev 169- Some minor code formatting changes 170 171### 0.3 - 28 September 2010 172- Moved entities rendering into the library 173 174### 0.2 - 17 September 2010 175- Added support for the Streaming API 176 177### 0.14 - 17 September 2010 178- Fixed authorisation header for use with OAuth Echo 179 180### 0.13 - 17 September 2010 181- Added use_ssl configuration parameter 182- Fixed config array typo 183- Removed v from the config 184- Remove protocol from the host (configured by use_ssl) 185- Added include for easier debugging 186 187### 0.12 - 17 September 2010 188 189- Moved curl options to config 190- Added the ability for curl to follow redirects, default false 191 192### 0.11 - 17 September 2010 193 194- Fixed a bug in the GET requests 195 196### 0.1 - 26 August 2010 197 198- Initial beta version 199 200## Community 201 202License: Apache 2 (see [included LICENSE file](https://github.com/themattharris/tmhOAuth/blob/master/LICENSE)) 203 204Follow [@tmhOAuth](https://twitter.com/intent/follow?screen_name=tmhOAuth) to receive updates on releases, or ask for support 205Follow me on Twitter: [@themattharris](https://twitter.com/intent/follow?screen_name=themattharris) 206Check out the Twitter Developer Resources: <https://dev.twitter.com> 207 208## To Do 209 210- Add good behavior logic to the Streaming API handler - i.e. on disconnect back off 211- Async Curl support