symfony · valeriangalliat · Feb 7, 2015 · Feb 7, 2015 · Feb 10, 2015
diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md
@@ -99,6 +99,18 @@ UPGRADE FROM 2.x to 3.0
    removed: `ContainerBuilder::synchronize()`, `Definition::isSynchronized()`,
    and `Definition::setSynchronized()`.
 
+### DomCrawler
+
+ * The `Form` class don't extend `Link` anymore. An `UriElementInterface`
+   interface have been introduced since 2.7 and both `Form` and `Link`
+   implement it. The abstract URI parsing logic is in an
+   `AbstractUriElement` class.
+ * The `node` and `method` properties from `AbstractUriElement` are now
+   private. You can access them with `getNode()` and `getMethod()`.
+ * The method `AbstractUriElement::setNode()` have been removed, child
+   classes now have to provide a `findNode` method that returns the node
+   instead of setting the (now private) `node` property.
+
 ### EventDispatcher
 
  * The interface `Symfony\Component\EventDispatcher\Debug\TraceableEventDispatcherInterface`

diff --git a/src/Symfony/Component/DomCrawler/AbstractUriElement.php b/src/Symfony/Component/DomCrawler/AbstractUriElement.php
@@ -0,0 +1,202 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DomCrawler;
+
+/**
+ * Any HTML element that can link to an URI.
+ *
+ * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @api
+ */
+abstract class AbstractUriElement implements UriElementInterface
+{
+    /**
+     * @var string The URI of the page where the element is embedded (or the base href)
+     */
+    protected $currentUri;
+
+    /**
+     * @var \DOMElement
+     */
+    private $node;
+
+    /**
+     * @var string The method to use for the element URI
+     */
+    private $method;
+
+    /**
+     * Constructor.
+     *
+     * @param \DOMElement $node       A \DOMElement instance
+     * @param string      $currentUri The URI of the page where the element is embedded (or the base href)
+     * @param string      $method     The method to use for the element URI (get by default)
+     *
+     * @throws \InvalidArgumentException if the node is not a link
+     *
+     * @api
+     */
+    public function __construct(\DOMElement $node, $currentUri, $method = 'GET')
+    {
+        if (!in_array(strtolower(substr($currentUri, 0, 4)), array('http', 'file'))) {
+            throw new \InvalidArgumentException(sprintf('Current URI must be an absolute URL ("%s").', $currentUri));
+        }
+
+        $this->node = $this->findNode($node);
+        $this->method = $method ? strtoupper($method) : null;
+        $this->currentUri = $currentUri;
+    }
+
+    public function getNode()
+    {
+        return $this->node;
+    }
+
+    public function getMethod()
+    {
+        return $this->method;
+    }
+
+    public function getUri()
+    {
+        $uri = trim($this->getRawUri());
+
+        // absolute URL?
+        if (null !== parse_url($uri, PHP_URL_SCHEME)) {
+            return $uri;
+        }
+
+        // empty URI
+        if (!$uri) {
+            return $this->currentUri;
+        }
+
+        // an anchor
+        if ('#' === $uri[0]) {
+            return $this->cleanupAnchor($this->currentUri).$uri;
+        }
+
+        $baseUri = $this->cleanupUri($this->currentUri);
+
+        if ('?' === $uri[0]) {
+            return $baseUri.$uri;
+        }
+
+        // absolute URL with relative schema
+        if (0 === strpos($uri, '//')) {
+            return preg_replace('#^([^/]*)//.*$#', '$1', $baseUri).$uri;
+        }
+
+        $baseUri = preg_replace('#^(.*?//[^/]*)(?:\/.*)?$#', '$1', $baseUri);
+
+        // absolute path
+        if ('/' === $uri[0]) {
+            return $baseUri.$uri;
+        }
+
+        // relative path
+        $path = parse_url(substr($this->currentUri, strlen($baseUri)), PHP_URL_PATH);
+        $path = $this->canonicalizePath(substr($path, 0, strrpos($path, '/')).'/'.$uri);
+
+        return $baseUri.('' === $path || '/' !== $path[0] ? '/' : '').$path;
+    }
+
+    /**
+     * Returns raw URI data.
+     *
+     * @return string
+     */
+    abstract protected function getRawUri();
+
+    /**
+     * Returns the canonicalized URI path (see RFC 3986, section 5.2.4).
+     *
+     * @param string $path URI path
+     *
+     * @return string
+     */
+    protected function canonicalizePath($path)
+    {
+        if ('' === $path || '/' === $path) {
+            return $path;
+        }
+
+        if ('.' === substr($path, -1)) {
+            $path = $path.'/';
+        }
+
+        $output = array();
+
+        foreach (explode('/', $path) as $segment) {
+            if ('..' === $segment) {
+                array_pop($output);
+            } elseif ('.' !== $segment) {
+                array_push($output, $segment);
+            }
+        }
+
+        return implode('/', $output);
+    }
+
+    /**
+     * Sets current \DOMElement instance.
+     *
+     * @param \DOMElement $node A \DOMElement instance
+     * @return \DOMElement
+     */
+    abstract protected function findNode(\DOMElement $node);
+
+    /**
+     * Removes the query string and the anchor from the given uri.
+     *
+     * @param string $uri The uri to clean
+     *
+     * @return string
+     */
+    private function cleanupUri($uri)
+    {
+        return $this->cleanupQuery($this->cleanupAnchor($uri));
+    }
+
+    /**
+     * Remove the query string from the uri.
+     *
+     * @param string $uri
+     *
+     * @return string
+     */
+    private function cleanupQuery($uri)
+    {
+        if (false !== $pos = strpos($uri, '?')) {
+            return substr($uri, 0, $pos);
+        }
+
+        return $uri;
+    }
+
+    /**
+     * Remove the anchor from the uri.
+     *
+     * @param string $uri
+     *
+     * @return string
+     */
+    private function cleanupAnchor($uri)
+    {
+        if (false !== $pos = strpos($uri, '#')) {
+            return substr($uri, 0, $pos);
+        }
+
+        return $uri;
+    }
+}
diff --git a/src/Symfony/Component/DomCrawler/CHANGELOG.md b/src/Symfony/Component/DomCrawler/CHANGELOG.md
@@ -1,6 +1,19 @@
 CHANGELOG
 =========
 
+3.0.0
+-----
+
+* [BC BREAK] `Form` now extends `AbstractUriElement` instead of `Link`.
+* [BC BREAK] The `node` and `method` properties of `AbstractUriElement` are now private (they already have public getters).
+* [BC BREAK] Since `node` is private, `setNode` in child classes can't set the `node` property directly, thus `setNode` have been renamed to `findNode` and now returns the node instead of setting the property.
+
+2.7.0
+-----
+
+* All the URI parsing logic have been abstracted in the `AbstractUriElement` class. The `Link` class is now a child of `AbstractUriElement` which implements the new `UriElementInterface`, describing the common `getNode`, `getMethod` and `getUri` methods.
+* Added an `Image` class to crawl images and parse their `src` attribute, and `selectImage`, `image`, `images` methods in `Crawler`, the image version of the equivalent `link` methods.
+
 2.5.0
 -----
 

diff --git a/src/Symfony/Component/DomCrawler/Crawler.php b/src/Symfony/Component/DomCrawler/Crawler.php
@@ -690,6 +690,22 @@ public function selectLink($value)
         return $this->filterRelativeXPath($xpath);
     }
 
+    /**
+     * Selects images by alt value.
+     *
+     * @param string $value The image alt
+     *
+     * @return Crawler A new instance of Crawler with the filtered list of nodes
+     *
+     * @api
+     */
+    public function selectImage($value)
+    {
+        $xpath = sprintf('descendant-or-self::img[contains(concat(\' \', normalize-space(string(@alt)), \' \'), %s)]', static::xpathLiteral(' '.$value.' '));
+
+        return $this->filterRelativeXPath($xpath);
+    }
+
     /**
      * Selects a button by name or alt value for images.
      *
@@ -748,6 +764,45 @@ public function links()
         return $links;
     }
 
+    /**
+     * Returns an Image object for the first node in the list.
+     *
+     * @param string $method The method for the image (get by default)
+     *
+     * @return Image An Image instance
+     *
+     * @throws \InvalidArgumentException If the current node list is empty
+     *
+     * @api
+     */
+    public function image($method = 'get')
+    {
+        if (!count($this)) {
+            throw new \InvalidArgumentException('The current node list is empty.');
+        }
+
+        $node = $this->getNode(0);
+
+        return new Image($node, $this->baseHref, $method);
+    }
+
+    /**
+     * Returns an array of Image objects for the nodes in the list.
+     *
+     * @return Image[] An array of Image instances
+     *
+     * @api
+     */
+    public function images()
+    {
+        $images = array();
+        foreach ($this as $node) {
+            $images[] = new Image($node, $this->baseHref, 'get');
+        }
+
+        return $images;
+    }
+
     /**
      * Returns a Form object for the first node in the list.
      *