= 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 one single class: `sfWebBrowser`. Unit tests are available in the SVN repository, to be placed in a symfony application&#039;s `test/` directory.

== Features ==

The `sfWebBrowser` class makes web requests based on a URI:
{{{
$b = new sfWebBrowser();
$b-&gt;get(&#039;http://www.example.com/&#039;);
$res = $b-&gt;getResponseText();
}}}

The usual methods of the `sfTestBrowser` also work there, with the fluid interface. 
{{{
// Inline
$b-&gt;get(&#039;http://www.example.com/&#039;)-&gt;get(&#039;http://www.google.com/&#039;)-&gt;back()-&gt;reload();
// More readable
$b-&gt;get(&#039;http://www.example.com/&#039;)
  -&gt;get(&#039;http://www.google.com/&#039;)
  -&gt;back()
  -&gt;reload();
}}}

The browser accepts absolute and relative URIs
{{{
$b-&gt;get(&#039;http://www.example.com/test.html&#039;);
$b-&gt;get(&#039;test.html&#039;);
}}}

The `get()` method accepts parameters either as a query string, or as an array.
{{{
$b-&gt;get(&#039;http://www.example.com/test.php?foo=bar&#039;);
$b-&gt;get(&#039;http://www.example.com/test.php&#039;, array(&#039;foo&#039;, &#039;bar&#039;));
}}}

Requests in POST mode are also supported.
{{{
$b-&gt;post(&#039;http://www.example.com/test.php&#039;, array(&#039;foo&#039;, &#039;bar&#039;));
}}}

You can access the response in various formats, at your convenience:
{{{
$myString         = $b-&gt;getResponseText();
$myString         = $b-&gt;getResponseBody(); // drop the &lt;head&gt; part
$myDomDocument    = $b-&gt;getResponseDom();
$myDomCssSelector = $b-&gt;getResponseDomCssSelector();
$mySimpleXml      = $b-&gt;getResponseXml();
}}}

You can also interact with the response with the `setFields()` and `click()` methods.

{{{
$b-&gt;get(&#039;http://www.example.com/login&#039;)
  -&gt;setField(&#039;user&#039;, &#039;foobar&#039;)
  -&gt;setField(&#039;password&#039;, &#039;barbaz&#039;)
  -&gt;click(&#039;submit&#039;);
}}}

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.

== 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 ==

The web request is made via `fopen()`, so this will only work if PHP is compiled with sockets support and if `allow_url_fopen` is defined to `true` in the `php.ini`.

Cookies are not handled yet.

Caching is not supported yet.

== Changelog ==

=== 2007-02-16 | 0.9.3 ===

 * tristan: Added support for gzip and deflate.
 * tristan: possibility to pass default request headers to sfWebBrowser&#039;s constructor
 * tristan: &quot;Accept-Encoding&quot; header is automatically set depending on PHP capabilities
 * tristan: Fixed problems with request and response headers case 
 * tristan: renamed &quot;browser options&quot; to &quot;adapter options&quot; (http://www.symfony-project.com/forum/index.php/m/21635/)
 * tristan: &#039;&#039;&#039;BC break&#039;&#039;&#039; 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