Ux Driver Laravel Package

Product Decisions This Supports

• Onboarding and feature-adoption UX in Symfony/Twig apps. This package is the server-rendered authoring layer for driver.js: product tours, step-by-step hints, and beacon callouts authored declaratively in Twig or programmatically in PHP, with Stimulus controllers emitted for you. It supports the "do we invest in guided onboarding this quarter?" decision without committing to a JS SPA rewrite.
• Build vs. buy for in-app guidance. The realistic alternative set is (a) hand-rolled driver.js glue in each app, (b) a commercial adoption platform (Appcues, Userpilot, Pendo), or (c) this package. This is the low-cost, self-hosted, no-vendor-contract option — appropriate when guidance is a feature of the product, not the product.
• Roadmap signal: this release adds zero capability. v0.2.0 is pure internal consolidation — no new driver.js option, no new authoring mode. So it should not move any roadmap item. What it does change is the cost of future options: the Html\DriverOptions sink list and the single Model\Options pipeline turn "add a driver.js option" from a four-call-site hunt into a one-line change. That is a concrete reduction in the lead time for any future "support option X" request, and worth noting when estimating upcoming tour customization asks.
• Maintenance-risk posture. StimulusContractTest parsing assets/src/ to fail the build when PHP and JS attribute names drift is the kind of thing you want to see before betting on a pre-1.0 dependency. It converts a class of silent runtime breakage into a red suite — relevant to any decision to depend on this in a customer-facing surface.
• Platform fit check. Requirements are unchanged: PHP 8.2+, Symfony 7.x/8.x, StimulusBundle 2.x/3.x, TwigComponent 2.x/3.x, Twig 3.8+, driver.js 1.8+. This is a Symfony UX bundle, not a Laravel package — if the target product is Laravel, this is the wrong dependency regardless of release quality. If the target is Symfony/Twig, fit is good and unchanged by this release.

When to Consider This Package

Consider it when:

• The application is Symfony 7/8 with Twig/TwigComponent, and onboarding UI is authored server-side rather than in a JS SPA.
• You want driver.js tours and hints declared in templates (or built in PHP services) rather than maintained as hand-written JSON config in JavaScript, and you want one source of truth for the PHP↔JS contract.
• Guidance content is owned by the product team and changes often — the option pipeline means new driver.js fields are cheap to expose, so you aren't blocked waiting on a wrapper upgrade each time marketing wants a new popover setting.
• You are comfortable pinning a pre-1.0 dependency and budgeting for occasional breaking changes on minor bumps.

Look elsewhere when:

• You are on Laravel. No Laravel integration exists here.
• You need the guidance platform, not the tour renderer — segmentation, A/B testing of tours, analytics funnels, non-engineer authoring UI. Those are buy decisions; this package renders tours, it does not measure them.
• You need SPA-native guidance in React/Vue where the tour state must live in the client store.
• Your team maintains custom Driver:Step / Driver:Hint templates. This release removed Step::titleHtml(), descriptionHtml(), sideValue(), alignValue() (and Hint equivalents) from the Twig components; the escaping now lives on Model\Step / Model\Hint. Shipped templates are fine, custom ones must be migrated. Combined with Model\Hint::$element becoming nullable and getElement(): ?string, this is a real if small migration — budget a half-day of template review, not a sprint.

How to Pitch It (Stakeholders)

To executives (one paragraph): We evaluated the Symfony UX Driver bundle at v0.2.0 as the mechanism for in-product onboarding tours and tooltips. This release adds no user-facing features — it is an internal cleanup that removes duplicated code across the Twig components, Twig builders and PHP builders. Its business value is narrower but real: it lowers the cost and risk of every future tour customization, and it adds automated tests that catch PHP/JS contract drift before it reaches customers. Recommendation: viable for a Symfony/Twig product, inappropriate for a Laravel one. Cost is low, vendor risk is zero, but it is pre-1.0 and should be pinned.

To engineering: No new API surface to adopt and no functional change on the happy path. Three things to know: (1) a <twig:Driver:Tour> no longer serializes animate, smoothScroll and allowClose unless explicitly set — the previously pinned values were driver.js defaults, so rendered behavior is identical, only the payload is shorter; showProgress is still forced true, now via Model\Tour::DEFAULTS. (2) Model\Hint::$element is nullable and getElement() returns ?string; the builder path is unchanged since Hints::addHint() still requires it. (3) The titleHtml() / descriptionHtml() / sideValue() / alignValue() helpers are gone from the Twig components — call Model\Step / Model\Hint instead. New public API (Model\Options, Enum\Normalizer, Model\OverlayOptions, Html\DriverOptions, StimulusContract, Tour::options(), Hints::options(), Hint::BEACON_OPTIONS) is worth knowing because it is where you extend options from now on — one entry in the per-type option table, not a new branch. Requirements are unchanged, so no dependency work.

To the product team: Nothing you can ship differently this sprint. The one process change worth adopting: when a tour needs a driver.js option the wrapper doesn't expose, the ask is now a small, well-scoped change rather than a refactor — treat those requests as normal backlog items instead of blocked-by-dependency items.