feature #4971 [DomCrawler] Document images crawler (valeriangalliat)

This PR was merged into the master branch.

Discussion
----------

[DomCrawler] Document images crawler

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#13649, symfony/symfony#13650)
| Applies to    | 3.0.0
| Fixed tickets | symfony/symfony#12429

Commits
-------

355a83f [DomCrawler] Document images crawler

Author: xabbuh

components/dom_crawler.rst

@@ -49,9 +49,11 @@ which are basically nodes that you can traverse easily::
         var_dump($domElement->nodeName);
     }
 
-Specialized :class:`Symfony\\Component\\DomCrawler\\Link` and
+Specialized :class:`Symfony\\Component\\DomCrawler\\Link`,
+:class:`Symfony\\Component\\DomCrawler\\Image` and
 :class:`Symfony\\Component\\DomCrawler\\Form` classes are useful for
-interacting with html links and forms as you traverse through the HTML tree.
+interacting with html links, images and forms as you traverse through the HTML
+tree.
 
 .. note::
 
@@ -293,7 +295,7 @@ Links
 ~~~~~
 
 To find a link by name (or a clickable image by its ``alt`` attribute), use
-the ``selectLink`` method on an existing crawler. This returns a Crawler
+the ``selectLink`` method on an existing crawler. This returns a ``Crawler``
 instance with just the selected link(s). Calling ``link()`` gives you a special
 :class:`Symfony\\Component\\DomCrawler\\Link` object::
 
@@ -317,6 +319,23 @@ methods to get more information about the selected link itself::
     page suffixed with ``#foo``. The return from ``getUri()`` is always a full
     URI that you can act on.
 
+Images
+~~~~~~
+
+To find an image by its ``alt`` attribute, use the ``selectImage`` method on an
+existing crawler. This returns a ``Crawler`` instance with just the selected
+image(s). Calling ``image()`` gives you a special
+:class:`Symfony\\Component\\DomCrawler\\Image` object::
+
+    $imagesCrawler = $crawler->selectImage('Kitten');
+    $image = $imagesCrawler->image();
+
+    // or do this all at once
+    $image = $crawler->selectImage('Kitten')->image();
+
+The :class:`Symfony\\Component\\DomCrawler\\Image` object has the same
+``getUri()`` method as :class:`Symfony\\Component\\DomCrawler\\Link`.
+
 Forms
 ~~~~~