Installation

UX Driver is a Symfony bundle that renders Driver.js Tours, Highlights, and Hints from Twig Components or from PHP builders. It ships Twig Components, Twig functions, autowired builder services, and two Stimulus controllers, so nothing about a Tour has to be written in application JavaScript.

It needs PHP 8.2+, Symfony 7 or 8, and Driver.js 1.8+. The full matrix lives in Compatibility.

Install

1. Require the bundle. Symfony Flex enables it for you.

   composer require pentiminax/ux-driver

2. Load the Driver.js stylesheets — the bundle ships the behavior, Driver.js ships the looks.

   AssetMapper

   Nothing to do. The bundle declares driver.js/dist/driver.css and driver.js/dist/hints.css as StimulusBundle autoimport assets, and the same paths are listed in the importmap metadata.

   Webpack Encore

   Import both files once, in your application entrypoint:

   import 'driver.js/dist/driver.css'
   import 'driver.js/dist/hints.css'

3. Declare a Tour — either as a component next to the markup it explains, or with a builder.

   Component

   <twig:Driver:Tour id="welcome">
       <button {{ ux_tour_action('start') }}>Start tour</button>
   
       <twig:Driver:Step :order="1" title="Dashboard" description="This is your daily overview">
           <h1>Dashboard</h1>
       </twig:Driver:Step>
   </twig:Driver:Tour>

   Twig builder

   {% set tour = create_tour('welcome')
       .addStep('.dashboard-title', 'Dashboard', 'This is your daily overview') %}
   
   <button {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>

   PHP builder

   use Pentiminax\UX\Driver\Builder\TourBuilder;
   
   public function __construct(private readonly TourBuilder $tourBuilder)
   {
   }
   
   public function dashboard(): Response
   {
       $tour = $this->tourBuilder->create('welcome')
           ->addStep('.dashboard-title', 'Dashboard', 'This is your daily overview');
   
       return $this->render('dashboard.html.twig', ['tour' => $tour]);
   }

   Then print the controller attributes in the template:

   <button {{ ux_tour(tour) }} {{ ux_tour_action('start') }}>Start tour</button>

The <twig:Driver:Tour> component renders the pentiminax--ux-driver--tour controller values, and each <twig:Driver:Step> renders its host element with the target attributes the controller reads on start. The builders produce the same values from a Tour object — TourBuilder and HintsBuilder are autowired services, so a controller only has to type-hint them.

Where to go next

• First Tour — a complete three-Step Tour, and the same Tour written with the builder.
• Hints — beacons that stay on the page after onboarding.
• Authoring modes — when to reach for components, and when for the Twig or PHP builders.