[Tree] Add pre-order and level-order traversals

doc/tree.md

@@ -1220,6 +1220,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.

src/Tree/Entity/Repository/NestedTreeRepository.php

@@ -36,6 +36,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)
@@ -905,6 +908,100 @@ 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 self::TRAVERSAL_* $traversalStrategy Strategy to use to traverse tree
+     *
+     * @throws InvalidArgumentException if input is invalid
+     *
+     * @return QueryBuilder QueryBuilder object
+     */
+    public function getNextNodesQueryBuilder($root, $node = null, int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER)
+    {
+        $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('Invalid traversal strategy.');
+        }
+
+        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
+     *
+     * @return Query
+     */
+    public function getNextNodesQuery($root, $node = null, int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER)
+    {
+        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
+     *
+     * @return object|null
+     */
+    public function getNextNode($root, $node = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER)
+    {
+        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<object>
+     */
+    public function getNextNodes($root, $node = null, int $limit = null, string $traversalStrategy = self::TRAVERSAL_PRE_ORDER)
+    {
+        return $this->getNextNodesQuery($root, $node, $limit, $traversalStrategy)->getArrayResult();
+    }
+
     protected function validate()
     {
         return Strategy::NESTED === $this->listener->getStrategy($this->_em, $this->getClassMetadata()->name)->getName();

tests/Gedmo/Tree/NestedTreeTraversalTest.php

@@ -0,0 +1,135 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Doctrine Behavioral Extensions package.
+ * (c) Gediminas Morkevicius <gediminas.morkevicius@gmail.com> 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 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
+{
+    public 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 ($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 \Doctrine\ORM\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();
+    }
+}