From 8baafa2bc0a2c7dc658f2853c04371d8aba5af45 Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Sat, 2 Jan 2021 17:25:53 +0100 Subject: [PATCH] deprecate parents() in favor of ancestors() --- UPGRADE-5.3.md | 5 +++ UPGRADE-6.0.md | 5 +++ src/Symfony/Component/DomCrawler/CHANGELOG.md | 1 + src/Symfony/Component/DomCrawler/Crawler.php | 16 +++++++++- .../DomCrawler/Tests/AbstractCrawlerTest.php | 31 ++++++++++++++++++- .../Component/DomCrawler/composer.json | 1 + 6 files changed, 57 insertions(+), 2 deletions(-) diff --git a/UPGRADE-5.3.md b/UPGRADE-5.3.md index 8ba314700e5e5..4e8ff1dc9de78 100644 --- 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 index 78124a7c53888..ba5084c7db73c 100644 --- 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 index 8a5b0e2341ea6..b7ba8b60b1a07 100644 --- 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 index 8775508512812..5dbd3b06da846 100644 --- 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 index 19c7e678acacd..3235c5539cd6d 100644 --- 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 index 786f3476d9b8d..9bccde48a7c3c 100644 --- 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"