diff --git a/CHANGELOG.md b/CHANGELOG.md index eb2725a72e..2d307c358d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,7 @@ a release. ### Added - Tree: Add `Nested::ALLOWED_NODE_POSITIONS` constant in order to expose the available node positions +- Tree: Add pre-order and level-order traversals (#2498). Add `getNextNode()` and `getNextNodes()` methods to traverse the tree - Support for `doctrine/collections` 2.0 - Support for `doctrine/event-manager` 2.0 - Loggable: Add `LogEntryInterface` interface in order to be implemented by log entry models diff --git a/doc/tree.md b/doc/tree.md index a64d4350a9..f0bf82ee1e 100644 --- a/doc/tree.md +++ b/doc/tree.md @@ -1249,6 +1249,11 @@ There are repository methods that are available for you in all the strategies: * childSort: array || keys allowed: field: field to sort on, dir: direction. 'asc' or 'desc' - *includeNode*: Using "true", this argument allows you to include in the result the node you passed as the first argument. Defaults to "false". * **setChildrenIndex** / **getChildrenIndex**: These methods allow you to change the default index used to hold the children when you use the **childrenHierarchy** method. Index defaults to "__children". +* **getNextNode** / **getNextNodes**: These methods allow you to get the next nodes when parsing a nested tree. Arguments: + - *root*: Root node use to select (sub-)tree to use. + - *node*: Current node. Use "null" to get the first one. Default to "null". + - *limit* (only for getNextNodes): Maximum nodes to return. Default to "null". + - *traversalStrategy*: Which strategy to use between "pre_order" and "level_order". Default to "NestedTreeRepository::TRAVERSAL_PRE_ORDER". This list is not complete yet. We're working on including more methods in the common API offered by repositories of all the strategies. Soon we'll be adding more helpful methods here. diff --git a/src/Tree/Entity/Repository/NestedTreeRepository.php b/src/Tree/Entity/Repository/NestedTreeRepository.php index 8fc45996f4..eae962261b 100644 --- a/src/Tree/Entity/Repository/NestedTreeRepository.php +++ b/src/Tree/Entity/Repository/NestedTreeRepository.php @@ -39,6 +39,9 @@ */ class NestedTreeRepository extends AbstractTreeRepository { + public const TRAVERSAL_PRE_ORDER = 'pre_order'; + public const TRAVERSAL_LEVEL_ORDER = 'level_order'; + /** * Allows the following 'virtual' methods: * - persistAsFirstChild($node) @@ -1158,6 +1161,96 @@ public function getNodesHierarchy($node = null, $direct = false, array $options return $this->getNodesHierarchyQuery($node, $direct, $options, $includeNode)->getArrayResult(); } + /** + * @param object $root Root node of the parsed tree + * @param object|null $node Current node. If null, first node will be returned + * @param int|null $limit Maximum nodes to return. If null, all nodes will be returned + * @param string $traversalStrategy Strategy to use to traverse tree + * + * @phpstan-assert self::TRAVERSAL_* $traversalStrategy + * + * @throws InvalidArgumentException if input is invalid + */ + public function getNextNodesQueryBuilder($root, $node = null, ?int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER): QueryBuilder + { + $meta = $this->getClassMetadata(); + $config = $this->listener->getConfiguration($this->_em, $meta->getName()); + + if (self::TRAVERSAL_PRE_ORDER === $traversalStrategy) { + $qb = $this->childrenQueryBuilder($root, false, $config['left'], 'ASC', true); + if (null !== $node) { + $wrapped = new EntityWrapper($node, $this->_em); + $qb + ->andWhere($qb->expr()->gt('node.'.$config['left'], ':lft')) + ->setParameter('lft', $wrapped->getPropertyValue($config['left'])) + ; + } + } elseif (self::TRAVERSAL_LEVEL_ORDER === $traversalStrategy) { + if (!isset($config['level'])) { + throw new \InvalidArgumentException('TreeLevel must be set to use level order traversal.'); + } + $qb = $this->childrenQueryBuilder($root, false, [$config['level'], $config['left']], ['DESC', 'ASC'], true); + if (null !== $node) { + $wrapped = new EntityWrapper($node, $this->_em); + $qb + ->andWhere( + $qb->expr()->orX( + $qb->expr()->andX( + $qb->expr()->gt('node.'.$config['left'], ':lft'), + $qb->expr()->eq('node.'.$config['level'], ':lvl') + ), + $qb->expr()->lt('node.'.$config['level'], ':lvl') + ) + ) + ->setParameter('lvl', $wrapped->getPropertyValue($config['level'])) + ->setParameter('lft', $wrapped->getPropertyValue($config['left'])) + ; + } + } else { + throw new InvalidArgumentException(\sprintf('Invalid traversal strategy "%s".', $traversalStrategy)); + } + + if (null !== $limit) { + $qb->setMaxResults($limit); + } + + return $qb; + } + + /** + * @param object $root Root node of the parsed tree + * @param object|null $node Current node. If null, first node will be returned + * @param int|null $limit Maximum nodes to return. If null, all nodes will be returned + * @param self::TRAVERSAL_* $traversalStrategy Strategy to use to traverse tree + */ + public function getNextNodesQuery($root, $node = null, ?int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER): Query + { + return $this->getNextNodesQueryBuilder($root, $node, $limit, $traversalStrategy)->getQuery(); + } + + /** + * @param object $root Root node of the parsed tree + * @param object|null $node Current node. If null, first node will be returned + * @param self::TRAVERSAL_* $traversalStrategy Strategy to use to traverse tree + */ + public function getNextNode($root, $node = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER): ?object + { + return $this->getNextNodesQuery($root, $node, 1, $traversalStrategy)->getOneOrNullResult(); + } + + /** + * @param object $root Root node of the parsed tree + * @param object|null $node Current node. If null, first node will be returned + * @param int|null $limit Maximum nodes to return. If null, all nodes will be returned + * @param self::TRAVERSAL_* $traversalStrategy Strategy to use to traverse tree + * + * @return array + */ + public function getNextNodes($root, $node = null, ?int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER): array + { + return $this->getNextNodesQuery($root, $node, $limit, $traversalStrategy)->getArrayResult(); + } + protected function validate() { return Strategy::NESTED === $this->listener->getStrategy($this->_em, $this->getClassMetadata()->name)->getName(); diff --git a/tests/Gedmo/Tree/NestedTreeTraversalTest.php b/tests/Gedmo/Tree/NestedTreeTraversalTest.php new file mode 100644 index 0000000000..cfc849d2e1 --- /dev/null +++ b/tests/Gedmo/Tree/NestedTreeTraversalTest.php @@ -0,0 +1,136 @@ + http://www.gediminasm.org + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Gedmo\Tests\Tree; + +use Doctrine\Common\EventManager; +use Doctrine\ORM\OptimisticLockException; +use Gedmo\Tests\Tool\BaseTestCaseORM; +use Gedmo\Tests\Tree\Fixture\RootCategory; +use Gedmo\Tree\TreeListener; + +/** + * These are tests for Tree traversal + */ +final class NestedTreeTraversalTest extends BaseTestCaseORM +{ + private const CATEGORY = RootCategory::class; + + protected function setUp(): void + { + parent::setUp(); + + $evm = new EventManager(); + $evm->addEventSubscriber(new TreeListener()); + + $this->getDefaultMockSqliteEntityManager($evm); + $this->populate(); + } + + /** + * @dataProvider provideNextNodes + */ + public function testNextNode(array $expected, string $strategy): void + { + $repo = $this->em->getRepository(self::CATEGORY); + $lvl1 = $repo->findOneBy(['title' => 'Part. 1']); + + $result = []; + + $current = null; + while (null !== ($current = $repo->getNextNode($lvl1, $current, $strategy))) { + $result[] = $current->getTitle(); + } + static::assertSame($expected, $result); + } + + /** + * @dataProvider provideNextNodes + */ + public function testNextNodes(array $expected, string $strategy): void + { + $repo = $this->em->getRepository(self::CATEGORY); + $lvl1 = $repo->findOneBy(['title' => 'Part. 1']); + + $nextNodes = $repo->getNextNodes($lvl1, null, 10, $strategy); + + static::assertSame($expected, array_column($nextNodes, 'title')); + } + + public function provideNextNodes(): iterable + { + yield 'Pre-order traversal' => [ + ['Part. 1', 'Part. 1.1', 'Part. 1.2', 'Part. 1.2.1', 'Part. 1.2.2', 'Part. 1.3'], + 'pre_order', + ]; + yield 'Level-order traversal' => [ + ['Part. 1.2.1', 'Part. 1.2.2', 'Part. 1.1', 'Part. 1.2', 'Part. 1.3', 'Part. 1'], + 'level_order', + ]; + } + + protected function getUsedEntityFixtures(): array + { + return [self::CATEGORY]; + } + + /** + * @throws OptimisticLockException + */ + private function populate(): void + { + $lvl1 = new RootCategory(); + $lvl1->setTitle('Part. 1'); + + $lvl2 = new RootCategory(); + $lvl2->setTitle('Part. 2'); + + $lvl11 = new RootCategory(); + $lvl11->setTitle('Part. 1.1'); + $lvl11->setParent($lvl1); + + $lvl12 = new RootCategory(); + $lvl12->setTitle('Part. 1.2'); + $lvl12->setParent($lvl1); + + $lvl121 = new RootCategory(); + $lvl121->setTitle('Part. 1.2.1'); + $lvl121->setParent($lvl12); + + $lvl122 = new RootCategory(); + $lvl122->setTitle('Part. 1.2.2'); + $lvl122->setParent($lvl12); + + $lvl13 = new RootCategory(); + $lvl13->setTitle('Part. 1.3'); + $lvl13->setParent($lvl1); + + $lvl21 = new RootCategory(); + $lvl21->setTitle('Part. 2.1'); + $lvl21->setParent($lvl2); + + $lvl22 = new RootCategory(); + $lvl22->setTitle('Part. 2.2'); + $lvl22->setParent($lvl2); + + $this->em->persist($lvl1); + $this->em->persist($lvl2); + $this->em->persist($lvl11); + $this->em->persist($lvl12); + $this->em->persist($lvl121); + $this->em->persist($lvl122); + $this->em->persist($lvl13); + $this->em->persist($lvl21); + $this->em->persist($lvl22); + $this->em->flush(); + $this->em->clear(); + } +}