Documented xml namespace autodiscovery.

jakzal · weaverryan · commit 827014eea11d · 2013-12-17T15:27:34.000-06:00
diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
@@ -95,6 +95,52 @@ To remove a node the anonymous function must return false.
     All filter methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
     instance with filtered content.
 
+Both :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath` and
+:method:`Symfony\\Component\\DomCrawler\\Crawler::filter` methods work with
+XML namespaces, which are automatically registered.
+
+.. versionadded:: 2.4
+    Auto discovery of namespaces was introduced in Symfony 2.4.
+
+Consider an XML below:
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <entry
+      xmlns="http://www.w3.org/2005/Atom"
+      xmlns:media="http://search.yahoo.com/mrss/"
+      xmlns:yt="http://gdata.youtube.com/schemas/2007">
+        <id>tag:youtube.com,2008:video:kgZRZmEc9j4</id>
+        <yt:accessControl action="comment" permission="allowed"/>
+        <yt:accessControl action="videoRespond" permission="moderated"/>
+        <media:group>
+            <media:title type="plain">Chordates - CrashCourse Biology #24</media:title>
+            <yt:aspectRatio>widescreen</yt:aspectRatio>
+        </media:group>
+    </entry>
+
+It can be filtered with ``DomCrawler`` without a need to register namespace
+aliases both with :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath`::
+
+    $crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');
+
+and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`::
+
+    use Symfony\Component\CssSelector\CssSelector;
+
+    CssSelector::disableHtmlExtension();
+    $crawler = $crawler->filter('default|entry media|group yt|aspectRatio');
+
+.. note::
+
+    The default namespace is registered with a name "default".
+
+.. caution::
+
+    To query an XML with a CSS selector, the HTML extension needs to be disabled with
+    :method:`Symfony\\Component\\CssSelector\\CssSelector::disableHtmlExtension`
+    to avoid converting the selector to lowercase.
+
+
 Node Traversing
 ~~~~~~~~~~~~~~~
 
