[DomCrawler] tagged the guaranteed BC API

src/Symfony/Component/DomCrawler/Crawler.php

@@ -17,6 +17,8 @@ use Symfony\Component\CssSelector\Parser as CssParser;
  * Crawler eases navigation of a list of \DOMNode objects.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class Crawler extends \SplObjectStorage
 {
@@ -32,6 +34,8 @@ class Crawler extends \SplObjectStorage
      * @param string $uri  The base URI to use for absolute links or form actions
      * @param string $base An optional base href for generating the uris for Form and Link.
      *                     This will be autodetected if $node has a <base> tag.
+     *
+     * @api
      */
     public function __construct($node = null, $uri = null, $base = null)
     {
@@ -48,6 +52,8 @@ class Crawler extends \SplObjectStorage
 
     /**
      * Removes all the nodes.
+     *
+     * @api
      */
     public function clear()
     {
@@ -61,6 +67,8 @@ class Crawler extends \SplObjectStorage
      * on the type of the argument.
      *
      * @param null|\DOMNodeList|array|\DOMNode $node A node
+     *
+     * @api
      */
     public function add($node)
     {
@@ -75,6 +83,12 @@ class Crawler extends \SplObjectStorage
         }
     }
 
+    /**
+     * Adds HTML/XML content.
+     *
+     * @param string $content A string to parse as HTML/XML
+     * @param string $type    The content type of the string
+     */
     public function addContent($content, $type = null)
     {
         if (empty($type)) {
@@ -103,6 +117,8 @@ class Crawler extends \SplObjectStorage
      *
      * @param string $content The HTML content
      * @param string $charset The charset
+     *
+     * @api
      */
     public function addHtmlContent($content, $charset = 'UTF-8')
     {
@@ -124,6 +140,8 @@ class Crawler extends \SplObjectStorage
      *
      * @param string $content The XML content
      * @param string $charset The charset
+     *
+     * @api
      */
     public function addXmlContent($content, $charset = 'UTF-8')
     {
@@ -139,6 +157,8 @@ class Crawler extends \SplObjectStorage
      * Adds a \DOMDocument to the list of nodes.
      *
      * @param \DOMDocument $dom A \DOMDocument instance
+     *
+     * @api
      */
     public function addDocument(\DOMDocument $dom)
     {
@@ -151,6 +171,8 @@ class Crawler extends \SplObjectStorage
      * Adds a \DOMNodeList to the list of nodes.
      *
      * @param \DOMNodeList $nodes A \DOMNodeList instance
+     *
+     * @api
      */
     public function addNodeList(\DOMNodeList $nodes)
     {
@@ -163,6 +185,8 @@ class Crawler extends \SplObjectStorage
      * Adds an array of \DOMNode instances to the list of nodes.
      *
      * @param array $nodes An array of \DOMNode instances
+     *
+     * @api
      */
     public function addNodes(array $nodes)
     {
@@ -175,6 +199,8 @@ class Crawler extends \SplObjectStorage
      * Adds a \DOMNode instance to the list of nodes.
      *
      * @param \DOMNode $node A \DOMNode instance
+     *
+     * @api
      */
     public function addNode(\DOMNode $node)
     {
@@ -191,6 +217,8 @@ class Crawler extends \SplObjectStorage
      * @param integer $position The position
      *
      * @return A new instance of the Crawler with the selected node, or an empty Crawler if it does not exist.
+     *
+     * @api
      */
     public function eq($position)
     {
@@ -218,6 +246,8 @@ class Crawler extends \SplObjectStorage
      * @param \Closure $closure An anonymous function
      *
      * @return array An array of values returned by the anonymous function
+     *
+     * @api
      */
     public function each(\Closure $closure)
     {
@@ -237,6 +267,8 @@ class Crawler extends \SplObjectStorage
      * @param \Closure $closure An anonymous function
      *
      * @return Crawler A Crawler instance with the selected nodes.
+     *
+     * @api
      */
     public function reduce(\Closure $closure)
     {
@@ -254,6 +286,8 @@ class Crawler extends \SplObjectStorage
      * Returns the first node of the current selection
      *
      * @return Crawler A Crawler instance with the first selected node
+     *
+     * @api
      */
     public function first()
     {
@@ -264,6 +298,8 @@ class Crawler extends \SplObjectStorage
      * Returns the last node of the current selection
      *
      * @return Crawler A Crawler instance with the last selected node
+     *
+     * @api
      */
     public function last()
     {
@@ -276,6 +312,8 @@ class Crawler extends \SplObjectStorage
      * @return Crawler A Crawler instance with the sibling nodes
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function siblings()
     {
@@ -292,6 +330,8 @@ class Crawler extends \SplObjectStorage
      * @return Crawler A Crawler instance with the next sibling nodes
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function nextAll()
     {
@@ -306,6 +346,8 @@ class Crawler extends \SplObjectStorage
      * Returns the previous sibling nodes of the current selection
      *
      * @return Crawler A Crawler instance with the previous sibling nodes
+     *
+     * @api
      */
     public function previousAll()
     {
@@ -322,6 +364,8 @@ class Crawler extends \SplObjectStorage
      * @return Crawler A Crawler instance with the parents nodes of the current selection
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function parents()
     {
@@ -347,6 +391,8 @@ class Crawler extends \SplObjectStorage
      * @return Crawler A Crawler instance with the children nodes
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function children()
     {
@@ -365,6 +411,8 @@ class Crawler extends \SplObjectStorage
      * @return string The attribute value
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function attr($attribute)
     {
@@ -381,6 +429,8 @@ class Crawler extends \SplObjectStorage
      * @return string The node value
      *
      * @throws \InvalidArgumentException When current node is empty
+     *
+     * @api
      */
     public function text()
     {
@@ -403,6 +453,8 @@ class Crawler extends \SplObjectStorage
      * @param array $attributes An array of attributes
      *
      * @return array An array of extracted values
+     *
+     * @api
      */
     public function extract($attributes)
     {
@@ -433,6 +485,8 @@ class Crawler extends \SplObjectStorage
      * @param string $xpath An XPath expression
      *
      * @return Crawler A new instance of Crawler with the filtered list of nodes
+     *
+     * @api
      */
     public function filterXPath($xpath)
     {
@@ -457,6 +511,8 @@ class Crawler extends \SplObjectStorage
      * @return Crawler A new instance of Crawler with the filtered list of nodes
      *
      * @throws \RuntimeException if the CssSelector Component is not available
+     *
+     * @api
      */
     public function filter($selector)
     {
@@ -475,6 +531,8 @@ class Crawler extends \SplObjectStorage
      * @param  string $value The link text
      *
      * @return Crawler A new instance of Crawler with the filtered list of nodes
+     *
+     * @api
      */
     public function selectLink($value)
     {
@@ -490,6 +548,8 @@ class Crawler extends \SplObjectStorage
      * @param  string $value The button text
      *
      * @return Crawler A new instance of Crawler with the filtered list of nodes
+     *
+     * @api
      */
     public function selectButton($value)
     {
@@ -508,6 +568,8 @@ class Crawler extends \SplObjectStorage
      * @return Link   A Link instance
      *
      * @throws \InvalidArgumentException If the current node list is empty
+     *
+     * @api
      */
     public function link($method = 'get')
     {
@@ -524,6 +586,8 @@ class Crawler extends \SplObjectStorage
      * Returns an array of Link objects for the nodes in the list.
      *
      * @return array An array of Link instances
+     *
+     * @api
      */
     public function links()
     {
@@ -544,6 +608,8 @@ class Crawler extends \SplObjectStorage
      * @return Form   A Form instance
      *
      * @throws \InvalidArgumentException If the current node list is empty
+     *
+     * @api
      */
     public function form(array $values = null, $method = null)
     {

src/Symfony/Component/DomCrawler/Field/ChoiceFormField.php

@@ -17,6 +17,8 @@ namespace Symfony\Component\DomCrawler\Field;
  * It is constructed from a HTML select tag, or a HTML checkbox, or radio inputs.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class ChoiceFormField extends FormField
 {
@@ -55,6 +57,8 @@ class ChoiceFormField extends FormField
      * Ticks a checkbox.
      *
      * @throws \InvalidArgumentException When value type provided is not correct
+     *
+     * @api
      */
     public function tick()
     {
@@ -69,6 +73,8 @@ class ChoiceFormField extends FormField
      * Ticks a checkbox.
      *
      * @throws \InvalidArgumentException When value type provided is not correct
+     *
+     * @api
      */
     public function untick()
     {

src/Symfony/Component/DomCrawler/Field/FileFormField.php

@@ -15,6 +15,8 @@ namespace Symfony\Component\DomCrawler\Field;
  * FileFormField represents a file form field (an HTML file input tag).
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class FileFormField extends FormField
 {
@@ -39,6 +41,8 @@ class FileFormField extends FormField
      * Sets the value of the field.
      *
      * @param string $value The value of the field
+     *
+     * @api
      */
     public function upload($value)
     {

src/Symfony/Component/DomCrawler/Field/InputFormField.php

@@ -18,6 +18,8 @@ namespace Symfony\Component\DomCrawler\Field;
  * specialized classes (cf. FileFormField and ChoiceFormField).
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class InputFormField extends FormField
 {

src/Symfony/Component/DomCrawler/Field/TextareaFormField.php

@@ -15,6 +15,8 @@ namespace Symfony\Component\DomCrawler\Field;
  * TextareaFormField represents a textarea form field (an HTML textarea tag).
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class TextareaFormField extends FormField
 {

src/Symfony/Component/DomCrawler/Form.php

@@ -17,6 +17,8 @@ use Symfony\Component\DomCrawler\Field\FormField;
  * Form represents an HTML form.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class Form implements \ArrayAccess
 {
@@ -39,6 +41,8 @@ class Form implements \ArrayAccess
      * @param string   $base   An optional base href for generating the submit uri
      *
      * @throws \LogicException if the node is not a button inside a form tag
+     *
+     * @api
      */
     public function __construct(\DOMNode $node, $method = null, $host = null, $path = '/', $base = null)
     {
@@ -76,6 +80,8 @@ class Form implements \ArrayAccess
      * Sets the value of the fields.
      *
      * @param array $values An array of field values
+     *
+     * @api
      */
     public function setValues(array $values)
     {
@@ -92,6 +98,8 @@ class Form implements \ArrayAccess
      * The returned array does not include file fields (@see getFiles).
      *
      * @return array An array of field values.
+     *
+     * @api
      */
     public function getValues()
     {
@@ -109,6 +117,8 @@ class Form implements \ArrayAccess
      * Gets the file field values.
      *
      * @return array An array of file field values.
+     *
+     * @api
      */
     public function getFiles()
     {
@@ -133,6 +143,8 @@ class Form implements \ArrayAccess
      * (like foo[bar] to arrays) like PHP does.
      *
      * @return array An array of field values.
+     *
+     * @api
      */
     public function getPhpValues()
     {
@@ -149,6 +161,8 @@ class Form implements \ArrayAccess
      * (like foo[bar] to arrays) like PHP does.
      *
      * @return array An array of field values.
+     *
+     * @api
      */
     public function getPhpFiles()
     {
@@ -168,6 +182,8 @@ class Form implements \ArrayAccess
      * @param Boolean $absolute Whether to return an absolute URI or not (this only works if a base URI has been provided)
      *
      * @return string The URI
+     *
+     * @api
      */
     public function getUri($absolute = true)
     {
@@ -207,6 +223,8 @@ class Form implements \ArrayAccess
      * If no method is defined in the form, GET is returned.
      *
      * @return string The method
+     *
+     * @api
      */
     public function getMethod()
     {
@@ -223,6 +241,8 @@ class Form implements \ArrayAccess
      * @param string $name The field name
      *
      * @return Boolean true if the field exists, false otherwise
+     *
+     * @api
      */
     public function has($name)
     {
@@ -233,6 +253,8 @@ class Form implements \ArrayAccess
      * Removes a field from the form.
      *
      * @param string $name The field name
+     *
+     * @api
      */
     public function remove($name)
     {
@@ -247,6 +269,8 @@ class Form implements \ArrayAccess
      * @return FormField The field instance
      *
      * @throws \InvalidArgumentException When field is not present in this form
+     *
+     * @api
      */
     public function get($name)
     {
@@ -263,6 +287,8 @@ class Form implements \ArrayAccess
      * @param string $name The field name
      *
      * @return FormField The field instance
+     *
+     * @api
      */
     public function set(Field\FormField $field)
     {
@@ -273,6 +299,8 @@ class Form implements \ArrayAccess
      * Gets all fields.
      *
      * @return array An array of fields
+     *
+     * @api
      */
     public function all()
     {

src/Symfony/Component/DomCrawler/Link.php

@@ -15,6 +15,8 @@ namespace Symfony\Component\DomCrawler;
  * Link represents an HTML link (an HTML a tag).
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
  */
 class Link
 {
@@ -34,6 +36,8 @@ class Link
      * @param strin    $base    An optional base href for generating the uri
      *
      * @throws \LogicException if the node is not a link
+     *
+     * @api
      */
     public function __construct(\DOMNode $node, $method = 'get', $host = null, $path = '/', $base = null)
     {
@@ -64,6 +68,8 @@ class Link
      * @param Boolean $absolute Whether to return an absolute URI or not (this only works if a base URI has been provided)
      *
      * @return string The URI
+     *
+     * @api
      */
     public function getUri($absolute = true)
     {
@@ -93,6 +99,8 @@ class Link
      * Gets the method associated with this link.
      *
      * @return string The method
+     *
+     * @api
      */
     public function getMethod()
     {