Download the PHP package rezozero/tree-walker without Composer

Tree Walker

Creates a configurable tree walker using different definitions for each node based on its PHP class or interface.

WalkerInterface implements \Countable in order to use it seamlessly in your PHP code and Twig templates. Each WalkerInterface will carry your node object and its children.

Since v1.1.0 AbstractWalker does not implement \IteratorAggregate in order to be compatible with api-platform normalizer (it normalizes it as a Hydra:Collection). But if you need it in you can add \IteratorAggregate to your custom Walker implementation, getIterator is already implemented.

If your application may introduce cyclic references between objects, you can use AbstractCycleAwareWalker instead of AbstractWalker to keep track of collected items and prevent collecting same item children twice. Collision detection is based on spl_object_id method.

Usage in Twig

• First, make sure your Walker instance implements \IteratorAggregate in order to use it directly into a loop

Walk forward

Here is an example of a recursive navigation item template using our WalkerInterface:

Walk backward

You can reverse walk (aka moon walking) to display a page breadcrumbs for example:

Configure your Walker

1. Create a WalkerContextInterface instance to hold every service your callable definitions will use to fetch each tree node children. For example: a Doctrine repository, a QueryBuilder, even your PDO instance.
2. Create a custom Walker class extending AbstractWalker.
   You’ll notice that AbstractWalker is very strict and prevents overriding its constructor in order to abstract all WalkerInterface instantiations from your business logic. All your custom logic must be included in definitions and countDefinitions.
3. Add definitions and countDefinitions from your custom Walker. A definition callable must return an array (or an iterable object) of your items. A countDefinition callable must return an int representing your items number. CountDefinitions are optional: AbstractWalker::count() method will fall back on using AbstractWalker::getChildren()->count().
4. Instantiate your custom Walker with your root item, and your context object

Here is some pseudo PHP code example:

Serialization groups

Any walker interface can be serialized with jms/serializer since they extends AbstractWalker class. You should add serialization groups to ensure you do not fall into an infinite loop:

• walker: serializes flat members with no recursion
• children: triggers walker children serialization until max level is reached.
• children_count: serializes children count if your application can count children array.
• walker_parent: triggers reverse walker parents serialization until root is reached.
• walker_level: serializes maximum and current level information.
• walker_metadata: serializes current level user metadata.

Obviously, do not use children and walker_parent groups at the same time…

Stoppable definition

You may want to prevent Walker to continue after a given item definition. For example to prevent infinite loops. You can write your definition class implementing StoppableDefinition interface.

If isStoppingCollectionOnceInvoked method return true, then each child won't have any children. It is useful when you want to prevent your tree to go deeper for specific item types. This is more specific than configuring the global maxLevel value on your tree-walker root instance.