Plot Branching Navigation

Plot Branching Navigation (PBN) allows different sequences of steps to be processed depending on user input. You've probably come across PBN when completing surveys and questionnaires: "If you answered Yes to Q3 goto Q10, else goto Q4"

An example: a survey is collecting information on the car you drive. Depending on the fuel type different questions can be asked; for example, What is the fuel consumption? for petrol and diesel cars, whereas Can you charge your car at home? is relevant for EVs.

Wizard allows us to this by setting up the steps array and choosing the appropriate branch in the Step event handler.

Steps Array

The steps array with PBN follows a simple pattern:

A step is a string that specifies the step name.
A branch group is an array; the keys are branch names, the values are arrays of steps and/or branch groups.

The only restriction is that the first entry must be a step.

ABNF Definition of Steps Array

c = "_" / ALPHA

Step = c *(c / DIGIT)

BranchName = 1*(c / DIGIT / "-")

Branch = "[" 1*(BranchName "=>[" 1*(Step / Branch) "],") "]"

StepsArray = "[" Step "," *(Step / Branch ",") "]"

Example Steps Array

Using the car example, the steps array might look something like:

                $steps = [
                    'make',
                    'model',
                    'fuel',
                    [
                        'fossil' => [
                            'tank_capacity',
                            'consumption',
                        ],
                        'electric' => [
                            'battery_capacity',
                            'home_charging',
                        ]
                    ],
                    'range'
                ];
            

Deciding on the Branch to Use

Deciding which branch to use is done in the Step event handler.

The 'fuel' step form will return the type of fuel the car uses; from that we can choose which branch to take. Our Step event handler for the 'fuel' step will be something like:

                private function fuel(Step $event)
                {
                    $formModel = new FuelForm();

                    if (
                        $this
                            ->formHydrator
                            ->populateFromPostAndValidate(
                                $formModel,
                                $event->getRequest()
                            )
                    ) {
                        $data = $formModel->getData();
                        $event->setData($data);

                        // Decide which branch to take
                        if ($data['fuel'] === self::FUEL_ELECTRIC) {
                            $event->setBranches([
                                'fossil' => Wizard::BRANCH_DISABLED
                                'electric' => Wizard::BRANCH_ENABLED
                            ]);
                        }

                        return;
                    }

                    $response = $this
                        ->viewRenderer
                        ->render('fuel', ['formModel' => $formModel])
                    ;

                    $event->setResponse($response);
                }
            

Default Branch

In the above example we check the fuel type and if it's electric we disable the fossil branch and enable the electric branch.

Why do we not enable the fossil branch and disable the electric branch if the fuel type is fossil? We don't have to because Wizard takes the default branch - the first branch in a branch group - by default.

You can disable this behaviour and skip all branch groups unless a branch is specifically enabled by calling Wizard::withDefaultBranch(!Wizard::DEFAULT_BRANCH) when setting up Wizard.

Last modified: 27 January 2025