deprecate parents() in favor of ancestors()

Author: xabbuh

CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 5.3.0
 -----
 
+ * The `parents()` method is deprecated. Use `ancestors()` instead.
  * Marked the `containsOption()`, `availableOptionValues()`, and `disableValidation()` methods of the
    `ChoiceFormField` class as internal
 

Crawler.php

@@ -494,13 +494,27 @@ public function previousAll()
     }
 
     /**
-     * Returns the parents nodes of the current selection.
+     * Returns the parent nodes of the current selection.
      *
      * @return static
      *
      * @throws \InvalidArgumentException When current node is empty
      */
     public function parents()
+    {
+        @trigger_deprecation('symfony/dom-crawler', '5.3', sprintf('The %s() method is deprecated, use ancestors() instead.', __METHOD__));
+
+        return $this->ancestors();
+    }
+
+    /**
+     * Returns the ancestors of the current selection.
+     *
+     * @return static
+     *
+     * @throws \InvalidArgumentException When the current node is empty
+     */
+    public function ancestors()
     {
         if (!$this->nodes) {
             throw new \InvalidArgumentException('The current node list is empty.');

Tests/AbstractCrawlerTest.php

@@ -12,10 +12,13 @@
 namespace Symfony\Component\DomCrawler\Tests;
 
 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\DomCrawler\Crawler;
 
 abstract class AbstractCrawlerTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
     abstract public function getDoctype(): string;
 
     protected function createCrawler($node = null, string $uri = null, string $baseHref = null)
@@ -409,7 +412,7 @@ public function testFilterXPath()
         $this->assertCount(6, $crawler->filterXPath('//li'), '->filterXPath() filters the node list with the XPath expression');
 
         $crawler = $this->createTestCrawler();
-        $this->assertCount(3, $crawler->filterXPath('//body')->filterXPath('//button')->parents(), '->filterXpath() preserves parents when chained');
+        $this->assertCount(3, $crawler->filterXPath('//body')->filterXPath('//button')->ancestors(), '->filterXpath() preserves ancestors when chained');
     }
 
     public function testFilterRemovesDuplicates()
@@ -1082,8 +1085,13 @@ public function testFilteredChildren()
         $this->assertEquals(1, $foo->children('.ipsum')->count());
     }
 
+    /**
+     * @group legacy
+     */
     public function testParents()
     {
+        $this->expectDeprecation('Since symfony/dom-crawler 5.3: The Symfony\Component\DomCrawler\Crawler::parents() method is deprecated, use ancestors() instead.');
+
         $crawler = $this->createTestCrawler()->filterXPath('//li[1]');
         $this->assertNotSame($crawler, $crawler->parents(), '->parents() returns a new instance of a crawler');
         $this->assertInstanceOf('Symfony\\Component\\DomCrawler\\Crawler', $crawler, '->parents() returns a new instance of a crawler');
@@ -1102,6 +1110,27 @@ public function testParents()
         }
     }
 
+    public function testAncestors()
+    {
+        $crawler = $this->createTestCrawler()->filterXPath('//li[1]');
+
+        $nodes = $crawler->ancestors();
+
+        $this->assertNotSame($crawler, $nodes, '->ancestors() returns a new instance of a crawler');
+        $this->assertInstanceOf(Crawler::class, $nodes, '->ancestors() returns a new instance of a crawler');
+
+        $this->assertEquals(3, $crawler->ancestors()->count());
+
+        $this->assertEquals(0, $this->createTestCrawler()->filterXPath('//html')->ancestors()->count());
+    }
+
+    public function testAncestorsThrowsIfNodeListIsEmpty()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        $this->createTestCrawler()->filterXPath('//ol')->ancestors();
+    }
+
     /**
      * @dataProvider getBaseTagData
      */

composer.json

@@ -17,6 +17,7 @@
     ],
     "require": {
         "php": ">=7.2.5",
+        "symfony/deprecation-contracts": "^2.1",
         "symfony/polyfill-ctype": "~1.8",
         "symfony/polyfill-mbstring": "~1.0",
         "symfony/polyfill-php80": "^1.15"