feature #39684 [DomCrawler] deprecate parents() in favor of ancestors() (xabbuh)

fabpot · fabpot · commit d2e589c0ecaf · 2021-01-03T09:15:45.000+01:00
This PR was merged into the 5.3-dev branch. Discussion ---------- [DomCrawler] deprecate parents() in favor of ancestors() | Q | A | ------------- | --- | Branch? | 5.x | Bug fix? | no | New feature? | yes | Deprecations? | yes | Tickets | Fix #26432 | License | MIT | Doc PR | Commits ------- 8baafa2 deprecate parents() in favor of ancestors()
diff --git a/UPGRADE-5.3.md b/UPGRADE-5.3.md
@@ -6,6 +6,11 @@ Asset
 
  * Deprecated `RemoteJsonManifestVersionStrategy`, use `JsonManifestVersionStrategy` instead.
 
+DomCrawler
+----------
+
+* Deprecated the `parents()` method, use `ancestors()` instead.
+
 Form
 ----
 
diff --git a/UPGRADE-6.0.md b/UPGRADE-6.0.md
@@ -33,6 +33,11 @@ DependencyInjection
  * The `ref()` function from the PHP-DSL has been removed, use `service()` instead.
  * Removed `Definition::setPrivate()` and `Alias::setPrivate()`, use `setPublic()` instead
 
+DomCrawler
+----------
+
+ * Removed the `parents()` method, use `ancestors()` instead.
+
 Dotenv
 ------
 
diff --git a/src/Symfony/Component/DomCrawler/CHANGELOG.md b/src/Symfony/Component/DomCrawler/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
 
diff --git a/src/Symfony/Component/DomCrawler/Crawler.php b/src/Symfony/Component/DomCrawler/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.');
diff --git a/src/Symfony/Component/DomCrawler/Tests/AbstractCrawlerTest.php b/src/Symfony/Component/DomCrawler/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
      */
diff --git a/src/Symfony/Component/DomCrawler/composer.json b/src/Symfony/Component/DomCrawler/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"
