= sfWebBrowser plugin = The `sfWebBrowserPlugin` proposes an HTTP client capable of making web requests. The interface is similar to that of `sfTestBrowser`. === Possible uses === * Querying a Web service * Monitoring a Website * Mashup of content from several websites * Aggregation of RSS feeds * Proxy to another server * Cross-domain AJAX interactions * API to foreign websites * ... == Contents == This plugin contains four classes: `sfWebBrowser`, `sfFopenAdapter`, `sfCurlAdapter`, and `sfSocketsAdapter`. Unit tests are available in the SVN repository, to be placed in a symfony application's `test/` directory. == Features == The `sfWebBrowser` class makes web requests based on a URI: {{{ $b = new sfWebBrowser(); $b->get('http://www.example.com/'); $res = $b->getResponseText(); }}} The usual methods of the `sfTestBrowser` also work there, with the fluid interface. {{{ // Inline $b->get('http://www.example.com/')->get('http://www.google.com/')->back()->reload(); // More readable $b->get('http://www.example.com/') ->get('http://www.google.com/') ->back() ->reload(); }}} The browser accepts absolute and relative URIs {{{ $b->get('http://www.example.com/test.html'); $b->get('test.html'); }}} The `get()` method accepts parameters either as a query string, or as an array. {{{ $b->get('http://www.example.com/test.php?foo=bar'); $b->get('http://www.example.com/test.php', array('foo', 'bar')); }}} POST, PUT and DELETE requests are also supported. {{{ $b->post('http://www.example.com/test.php', array('foo', 'bar')); $b->put('http://www.example.com/test.php', array('foo', 'bar')); $b->delete('http://www.example.com/test.php', array('foo', 'bar')); }}} You can access the response in various formats, at your convenience: {{{ $myString = $b->getResponseText(); $myString = $b->getResponseBody(); // drop the part $myDomDocument = $b->getResponseDom(); $myDomCssSelector = $b->getResponseDomCssSelector(); $mySimpleXml = $b->getResponseXml(); }}} You can also interact with the response with the `setFields()` and `click()` methods. {{{ $b->get('http://www.example.com/login') ->setField('user', 'foobar') ->setField('password', 'barbaz') ->click('submit'); }}} The browser supports HTTP and HTTPS requests, proxies, redirects, and timeouts. Gzip and deflate content-encoded response bodies are also supported, provided that you have the [http://php.net/zlib zlib extention] enabled. == Adapters == The browser can use various adapters to perform the requests: * `sfFopenAdapter` (default): Uses [http://php.net/fopen `fopen()`] to fetch pages. `fopen()` can take an URL as a parameter provided that PHP is compiled with sockets support, and `allow_url_fopen` is defined to `true` in `php.ini`. This is the case in most PHP distributions, so the default adapter should work in almost every platform. On the other hand, the compatibility has a cost: this adapter is slow. * `sfCurlAdapter`: Uses [http://php.net/curl Curl] to fetch pages. This adapter is a lot faster than `sfFopenAdapter`, however PHP must be compiled with the `with-curl` option, and the `curl` extension must be enabled in `php.ini` (which is rarely the case by default) for it to work. * `sfSocketsAdapter`: Uses [http://php.net/fsockopen `fsockopen()`] to fetch pages. You can specify an adapter when you create a new browser object, as follows: {{{ // use default adapter, i.e. sfFopenAdapter $b = new sfWebBrowser(array()); // use sfCurlAdapter $b = new sfWebBrowser(array(), 'sfCurlAdapter'); }}} == Usage == `sfWebBrowser` distiguishes to types of error: adapter errors and response errors. Thus, `sfWebBrowser` calls should be run this way : {{{ $b = new sfWebBrowser(); try { if (!$b->get($url)->responseIsError()) { // Successful response (eg. 200, 201, etc) } else { // Error response (eg. 404, 500, etc) } } catch (Exception $e) { // Adapter error (eg. Host not found) } }}} Besides, you should always remember that the response contents may contain incorrect code. Consider it as 'tainted', and therefore always use the [http://www.symfony-project.com/book/trunk/07-Inside-the-View-Layer#Output%20Escaping escaping] when outputting it to a template. {{{ // In the action $this->title = (string) $b->getResponseXml()->body->h1 // In the template get('title') // correct ?> }}} == Installation == * Install the plugin {{{ $ symfony plugin-install http://plugins.symfony-project.com/sfWebBrowserPlugin }}} * Clear the cache to enable the autoloading to find the new class {{{ $ symfony cc }}} == Known limitations == If `allow_url_fopen` is not defined to `true` and if the curl extension cannot be activated in the `php.ini` file, the browser can't fetch pages. Workaround (todo): use a sockets adapter. Cookies are not handled yet. Caching is not supported yet. == Changelog == === trunk === === 2007-03-27 | 1.0.1 stable === * bmeynell: Fixed a bug with `sfCurlAdapter` causing 'Bad Request' error responses * francois: Fixed a bug with `get()` when `arg_separator.output` is not set to '&' in `php.ini` (patch from river.bright) * francois: Fixed a bug with `get()` when query string is already present in the url (based on a patch from Jeff Merlet) * francois: Fixed auto-adapter decision in `sfWebBrowser::__construct()` === 2007-03-08 | 1.0.0 stable === * francois: Added auto-adapter decision in `sfWebBrowser::__construct()` * francois: Changed tested URLs a bit to avoid redirection issues with google * bmeynell: Added `sfSocketsAdapter` * bmeynell: `sfCurlAdapter`: more detailed error messages & leaner request setup === 2007-02-22 | 0.9.6 Beta === * bmeynell, tristan: Allowed for requests with any method in `sfCurlAdapter` * tristan: Added `sfWebBrowser::responseIsError()` * tristan: Added `sfWebBrowser::getResponseMessage()` * tristan: Refactored error management in `sfFopenAdapter` === 2007-02-21 | 0.9.5 Beta === * bmeynell: Fixed bug with relative uri's attempting to use a port other than 80 (sfWebBrowser, 132 - 146) * bmeynell: Fixed small bug not printing hostname on exception (sfFopenAdapter, 61-62) * bmeynell: Created sfCurlAdapter and passes all unit tests * bmeynell: Removed '$changeStack = true' from call() prototype in sfCurlAdapter, sfFopenAdapter, and moved changestack check to sfWebBrowser * bmeynell: Added $askeet_url to sfWebBrowserTest * bmeynell: Added easy toggling between adapters in sfWebBrowserTest * tristan: Added put() and delete() public methods * tristan: Added unit tests to validate request HTTP method === 2007-02-16 | 0.9.4 Beta === * francois: Refactored the browser to make it multi-adapter * francois: '''BC break''' constructor signature changed : `new sfWebBrowser(array $headers, string $adapter_class, array $adapter_options)` * francois: Fixed notice when trying to retrieve inexistent header * francois: Fixed header case normalization * francois: Transformed setResponseXXX() methods to public * francois: Fixed caps in `initializeRequestHeaders()` * francois: Fixed unit test #40 === 2007-02-16 | 0.9.3 Beta === * tristan: Added support for gzip and deflate. * tristan: Possibility to pass default request headers to sfWebBrowser's constructor * tristan: "Accept-Encoding" header is automatically set depending on PHP capabilities * tristan: Fixed problems with request and response headers case * tristan: Renamed "browser options" to "adapter options" (http://www.symfony-project.com/forum/index.php/m/21635/) * tristan: '''BC break''' constructor signature changed : `new sfWebBrowser(array $headers, array $adapter_options)` * tristan: Unit tested POST requests * tristan: Changed way httpd headers are stored internally * tristan: Fixed small bug in `getResponseBody()` * francois: Fixed unit test for malformed headers === 2007-02-09 | 0.9.2 Beta === * francois: Fixed notice with `getResponseXML()` === 2007-02-08 | 0.9.1 Beta === * francois: Fixed notice with some headers * francois: Added license and copyright === 2007-02-08 | 0.9.0 Beta === * francois: Initial release