Configuration Guide 🛠️

Welcome to the configuration guide for the Laravel Driver.js package! In this guide, we'll walk you through the various configuration options available to customize the behavior of Laravel Driver.js in your Laravel application.

Publishing the Config

The configuration file is published to config/driverjs.php when you run php artisan driverjs:install. You can also publish it manually:

php artisan vendor:publish --tag=driverjs-config

Driver.js Version 📦

By default, the package loads Driver.js v1.4.0 from the jsDelivr CDN. You can pin to a specific version or use latest to always get the newest release:

'version' => env('DRIVERJS_VERSION', '1.4.0'),

Set the DRIVERJS_VERSION environment variable to override this without modifying the config file directly.

Asset Source 🌐

This option controls how the Driver.js CSS and JavaScript assets are loaded. Supported values: "cdn", "npm", or "custom".

'asset_source' => env('DRIVERJS_ASSET_SOURCE', 'cdn'),

Value	Description
cdn	Loads assets from jsDelivr CDN. No build step required.
npm	Expects you to install driver.js via npm/pnpm/yarn and bundle it with Vite. Asset directives and renderAssetLinks() return an empty string in this mode.
custom	You manage asset inclusion yourself. The package will not inject any scripts or stylesheets.

CDN URL Overrides 🔗

If you want to use a custom CDN or self-hosted files, you can override the default CDN URLs:

'cdn_js_url' => env('DRIVERJS_CDN_JS_URL', null),
'cdn_css_url' => env('DRIVERJS_CDN_CSS_URL', null),

When set to null, the package will use the default jsDelivr URLs based on the configured version above.

Default Driver Configuration ⚙️

These options define the global defaults for every Driver.js instance created through the package. You can override any of these at runtime using the fluent builder methods.

'defaults' => [
    'animate' => true,
    'overlay_color' => '#000',
    'overlay_opacity' => 0.7,
    'smooth_scroll' => false,
    'allow_close' => true,
    'overlay_click_behavior' => 'close',
    'stage_padding' => 10,
    'stage_radius' => 5,
    'allow_keyboard_control' => true,
    'disable_active_interaction' => false,
],

Option	Default	Description
animate	true	Animate transitions between tour steps
overlay_color	'#000'	Overlay color (any valid CSS color)
overlay_opacity	0.7	Overlay opacity (0.0 to 1.0)
smooth_scroll	false	Smooth scroll to highlighted elements
allow_close	true	Allow closing by clicking overlay or pressing Escape
overlay_click_behavior	'close'	Action on overlay click: "close", "nextStep", or a JavaScript callback
stage_padding	10	Padding (px) between element and cutout
stage_radius	5	Border radius (px) of the cutout
allow_keyboard_control	true	Enable keyboard navigation (Escape, Arrow keys)
disable_active_interaction	false	Disable clicking the highlighted element

Default Popover Configuration 💬

These options control the appearance and behaviour of the popover that appears alongside each highlighted element.

'popover' => [
    'class' => '',
    'offset' => 10,
    'show_buttons' => ['next', 'previous', 'close'],
    'disable_buttons' => [],
    'show_progress' => false,
    'progress_text' => '{{current}} of {{total}}',
    'next_btn_text' => 'Next →',
    'prev_btn_text' => '← Previous',
    'done_btn_text' => 'Done',
],

Option	Default	Description
class	''	Custom CSS class on the popover wrapper
offset	10	Distance (px) between popover and element
show_buttons	['next', 'previous', 'close']	Buttons to display
disable_buttons	[]	Buttons to visually disable (greyed out)
show_progress	false	Show "X of Y" progress indicator
progress_text	' of '	Progress text template
next_btn_text	'Next →'	Next button label
prev_btn_text	'← Previous'	Previous button label
done_btn_text	'Done'	Done button label (shown on last step)

Tour Storage Configuration 💾

When a user completes a tour, the package can remember this so the tour is not shown again on subsequent visits.

'storage' => [
    'driver' => env('DRIVERJS_STORAGE_DRIVER', 'session'),
    'key_prefix' => 'driverjs_tour_',
    'cache_store' => env('DRIVERJS_CACHE_STORE', null),
],

Driver	Description	Persistence
session	Stores in Laravel session	Until browser closes
cache	Stores in Laravel cache	Configurable TTL (default: 1 year)
database	Stores in database table	Permanent (until reset)
null	Disables tracking	N/A

When using the cache driver, you can specify which cache store to use via the DRIVERJS_CACHE_STORE environment variable. When set to null, the default cache store is used.

When using the database driver, you'll need to publish and run the migration:

php artisan vendor:publish --tag=driverjs-migrations
php artisan migrate

Route Middleware 🔒

The package registers one internal HTTP route for tour completion tracking. By default it carries no extra middleware. You can protect it using the route_middleware option:

'route_middleware' => env('DRIVERJS_ROUTE_MIDDLEWARE', null),

Examples:

// Require the web middleware stack (session, CSRF)
'route_middleware' => 'web',

// Require authentication (recommended with the database storage driver)
'route_middleware' => ['web', 'auth'],

// No middleware (default)
'route_middleware' => null,

Set the environment variable to avoid modifying the config file directly:

DRIVERJS_ROUTE_MIDDLEWARE=web,auth

When using the database storage driver, always add auth middleware so that anonymous requests do not attempt to record completions (they would silently fail since there is no auth()->id() to associate with).

That's it! You now have the knowledge to fine-tune the Laravel Driver.js package to suit your specific needs. Happy configuring! 🛠️