-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add browserkit component documentation #4312
Closed
Closed
Changes from all commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
f4732a9
added introduction
9cda982
fixed a few mistakes
33a3a64
syntax fix
9ae95dc
added in sections that I apln to fill out
4d9e48d
added links with info about clients and packagist link
59a9dbf
added links to index and map files
f956182
make a basic request
51f320a
fixed spelling
d4c24e4
added a link snippit
cd4f6ec
more outlines, fixed link, added more about creating a client
05c89d5
added form submissions and moved creating a client to top
yamiko-ninja 982476e
added docs on histroy
yamiko-ninja 0923ac4
Adding documentation for cookies
2731858
spelling and formating
yamiko-ninja f119848
fix title underline
yamiko-ninja File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
BrowserKit | ||
========== | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
introduction |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,238 @@ | ||
.. index:: | ||
single: BrowserKit | ||
single: Components; BrowserKit | ||
|
||
The BrowserKit Component | ||
======================== | ||
|
||
The BrowserKit component simulates the behavior of a web browser. | ||
|
||
The BrowserKit component allows you to make web requests, click on links and submit forms. | ||
|
||
Installation | ||
------------ | ||
|
||
You can install the component in two different ways: | ||
|
||
* :doc:`Install it via Composer </components/using_components>` (``symfony/browser-kit`` on `Packagist`_); | ||
* Use the official Git repository (https://github.com/symfony/BrowserKit). | ||
|
||
Basic Usage | ||
----------- | ||
|
||
.. note:: | ||
|
||
The component only provides an abstract client and does not provide any "default" backend for the HTTP layer. | ||
|
||
Creating a Client | ||
----------------- | ||
|
||
To create your own client you must extend the abstract client class and implement the doRequest method. | ||
This method accepts a requests and should return a response. | ||
|
||
.. code-block:: php | ||
|
||
namespace ACME; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. should be There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No, we are in the components section here. It should not use framework things like bundles |
||
|
||
use Symfony\Component\BrowserKit\Client as BaseClient; | ||
use Symfony\Component\BrowserKit\Response; | ||
|
||
class Client extends BaseClient | ||
{ | ||
protected function doRequest($request) | ||
{ | ||
// convert request into a response | ||
// ... | ||
return new Response($content, $status, $headers); | ||
} | ||
} | ||
|
||
For a simple implementation of a browser based on an HTTP layer, have a look at Goutte_. | ||
|
||
For an implementation based on ``HttpKernelInterface``, have a look at the Client provided by the :doc:`/components/http_kernel/introduction`. | ||
|
||
|
||
Making Requests | ||
~~~~~~~~~~~~~~~ | ||
|
||
To make a request you use the client's request_ method. | ||
The first two arguments are for the HTTP method and the request URL. | ||
The request method will return a crawler object. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
$client = new Client(); | ||
$crawler = $client->request('GET', 'http://symfony.com'); | ||
|
||
Clicking Links | ||
~~~~~~~~~~~~~~ | ||
|
||
Select a link with the crawler and pass it to the click_ method to click on the link. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
$client = new Client(); | ||
$crawler = $client->request('GET', 'http://symfony.com'); | ||
$link = $crawler->selectLink('Go elsewhere...')->link(); | ||
$client->click($link); | ||
|
||
Submiting Forms | ||
~~~~~~~~~~~~~~~ | ||
|
||
You can submit forms with the submit method which takes a form object. | ||
You can get the form object by using the crawler to select the button and running the form method. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// make a real request to an external site | ||
$client = new Client(); | ||
$crawler = $client->request('GET', 'https://github.com/login'); | ||
|
||
// select the form and fill in some values | ||
$form = $crawler->selectButton('Log in')->form(); | ||
$form['login'] = 'symfonyfan'; | ||
$form['password'] = 'anypass'; | ||
|
||
// submit that form | ||
$crawler = $client->submit($form); | ||
|
||
Cookies | ||
------- | ||
|
||
Retreiving Cookies | ||
~~~~~~~~~~~~~~~~~~ | ||
|
||
The Crawler has a cookieJar which is a container for storing and recieving cookies. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// Make a request | ||
$client = new Client(); | ||
$crawler = $client->request('GET', 'http://symfony.com'); | ||
|
||
// Get the cookie Jar | ||
$cookieJar = $crawler->getCookieJar(); | ||
|
||
// Get a cookie by name | ||
$flavor = $cookieJar->get('flavor'); | ||
|
||
// Get cookie data | ||
$name = $flavor->getName(); | ||
$value = $flavor->getValue(); | ||
$raw = $flavor->getRawValue(); | ||
$secure = $flavor->isSecure(); | ||
$isHttpOnly = $flavor->isHttpOnly(); | ||
$isExpired = $flavor->isExpired(); | ||
$expires = $flavor->getExpiresTime(); | ||
$path = $flavor->getPath(); | ||
$domain = $flavor->getDomain(); | ||
|
||
Looping Through Cookies | ||
~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// Make a request | ||
$client = new Client(); | ||
$crawler = $client->request('GET', 'http://symfony.com'); | ||
|
||
// Get the cookie Jar | ||
$cookieJar = $crawler->getCookieJar(); | ||
|
||
// Get array with all cookies | ||
$cookies = $cookieJar->all(); | ||
foreach($cookies as $cookie) | ||
{ | ||
// ... | ||
} | ||
|
||
// Get all values | ||
$values = $cookieJar->allValues('http://symfony.com'); | ||
foreach($values as $value) | ||
{ | ||
// ... | ||
} | ||
|
||
// Get all raw values | ||
$rawValues = $cookieJar->allRawValues('http://symfony.com'); | ||
foreach($rawValues as $rawValue) | ||
{ | ||
// ... | ||
} | ||
|
||
.. note:: | ||
These cookie jar methods only return cookies that have not expired. | ||
|
||
Setting Cookies | ||
~~~~~~~~~~~~~~~ | ||
|
||
You can define create cookies and add them to a cookie jar that can be injected it into the client constructor. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// create cookies and add to cookie jar | ||
$expires = new \DateTime(); | ||
$expires->add(new \DateInterval('P1D')); | ||
$cookie = new Cookie( | ||
'flavor', | ||
'chocolate chip', | ||
$now->getTimestamp() | ||
); | ||
|
||
// create a client and set the cookies | ||
$client = new Client(array(), array(), $cookieJar); | ||
// ... | ||
|
||
History | ||
------- | ||
|
||
The client stores all your requests allowing you to go back and forward in your history. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// make a real request to an external site | ||
$client = new Client(); | ||
$home_crawler = $client->request('GET', 'http://symfony.com'); | ||
|
||
// select and click on a link | ||
$doc_link = $crawler->selectLink('Documentation')->link(); | ||
$doc_crawler = $client->click($link); | ||
|
||
// go back to home page | ||
$home_crawler = $client->back(); | ||
|
||
// go forward to documentation page | ||
$doc_crawler = $client->forward(); | ||
|
||
You can restart the client's history with the restart method. This will also clear out the CookieJar. | ||
|
||
.. code-block:: php | ||
|
||
use ACME\Client; | ||
|
||
// make a real request to an external site | ||
$client = new Client(); | ||
$home_crawler = $client->request('GET', 'http://symfony.com'); | ||
|
||
// restart history | ||
$client->restart(); | ||
|
||
|
||
.. _Packagist: https://packagist.org/packages/symfony/browser-kit | ||
.. _Goutte: https://github.com/fabpot/Goutte | ||
.. _request: http://api.symfony.com/2.3/Symfony/Component/BrowserKit/Client.html#method_request | ||
.. _click: http://api.symfony.com/2.3/Symfony/Component/BrowserKit/Client.html#method_click |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There should be a blank line between the directive and its contents.