Filament Tour Laravel Package

Technical Evaluation

Architecture Fit

• Filament Plugin Compatibility: The package is a Filament-specific plugin, leveraging Filament’s plugin system (Panel::plugins()). This ensures seamless integration with Filament’s architecture (v2-v5), aligning with Laravel’s modular design.
• DriverJS Integration: Under the hood, it uses DriverJS, a lightweight tour library, which is well-suited for interactive onboarding. This avoids reinventing wheel while providing Filament-specific abstractions.
• Event-Driven Design: The package emits events (filament-tour::open-tour, filament-tour::open-highlight) for dynamic triggering, fitting Laravel’s event system and Filament’s Livewire/AlpineJS ecosystem.

Integration Feasibility

• Low Friction: Installation is straightforward via Composer, with minimal configuration (publish config/views if needed). The plugin system abstracts away DriverJS setup.
• Filament Version Support: Explicit support for Filament v2–v5 reduces version conflicts, though v5.x is the latest focus (per last release date).
• Customization Points:
  • Tours/Highlights: Define via PHP methods (e.g., Tour::make()->steps()) or JSON.
  • Conditional Logic: Supports closures for dynamic visibility (e.g., ->visible(fn() => auth()->user()->hasSeenTour())).
  • Event Triggers: Hook into Livewire/AlpineJS via $dispatch() or Livewire.dispatch().

Technical Risk

• Maintainer Status: The package is unmaintained (author notes heavy workload). Risk of:
  • Bugs in newer Filament versions (v5+).
  • Missing features (e.g., Filament v6 compatibility).
  • Mitigation: Fork or patch locally; community contributions may fill gaps.
• DriverJS Dependencies: DriverJS is a third-party library with its own lifecycle. Ensure no breaking changes in future versions.
• CSS Selector Reliance: Tours/Highlights depend on stable selectors. Fragile if Filament’s UI changes (e.g., class names).
• Storage for "Only Visible Once": Uses localStorage; may conflict with privacy tools or multi-tab scenarios.

Key Questions

1. Filament Version Lock: Is the project locked to a specific Filament version (e.g., v5)? If not, how will you handle upgrades?
2. Tour Complexity: Will tours require dynamic logic (e.g., user-specific steps)? If so, test closures/JSON flexibility.
3. Performance: Will tours run on every page load? Consider lazy-loading or route-based triggers.
4. Fallbacks: Plan for DriverJS failures (e.g., polyfills for older browsers).
5. Testing: How will you verify tours work across dark/light themes and responsive layouts?
6. Analytics: Can you track tour completion rates (e.g., via Laravel events or frontend analytics)?

Integration Approach

Stack Fit

• Laravel/PHP: Native integration via Composer and Filament’s plugin system. No JavaScript required beyond DriverJS (included).
• Frontend: Works with Filament’s Livewire/AlpineJS out of the box. Events align with Filament’s dispatch system.
• Database: No schema changes needed; uses localStorage for "only visible once" tracking.
• Testing: Supports PHPUnit (for tour logic) and browser testing (for DriverJS rendering).

Migration Path

1. Assess Filament Version:
   • If using Filament v5, use jibaymcs/filament-tour:^5.0.
   • For v4/v3/v2, pin to respective versions (riskier due to maintenance).
2. Installation:

   composer require jibaymcs/filament-tour:"^5.0"
   php artisan vendor:publish --tag="filament-tour-config"  # Optional
   

3. Plugin Registration: Add to Panel configuration:

   ->plugins([FilamentTourPlugin::make()->enableCssSelector()])  // Enable dev tool
   

4. Define Tours/Highlights:
   • Option A: PHP-based (recommended for dynamic logic):

     use JibayMcs\FilamentTour\Tour\Tour;
     public function tours(): array {
         return [Tour::make('dashboard')->steps(Step::make()->title("..."))];
     }
     

   • Option B: JSON-based (for static tours):

     Tour::make(json: Storage::get('tours/dashboard.json'))
     

5. Trigger Tours Dynamically:
   • Via events (e.g., after user action):

     $this->dispatch('filament-tour::open-tour', 'dashboard');
     

   • Via UI buttons (AlpineJS/Livewire):

     <button x-on:click="$dispatch('filament-tour::open-tour', 'dashboard')">
         Start Tour
     </button>
     

Compatibility

• Filament Plugins: Conflicts unlikely, but test with other plugins using localStorage or DriverJS.
• Custom Filament Themes: Ensure highlight colors (->colors()) match your theme.
• Browser Support: DriverJS supports modern browsers; test edge cases (e.g., IE11 if required).

Sequencing

1. Phase 1: Install and verify basic tour rendering.
2. Phase 2: Implement dynamic tours (e.g., user-specific steps).
3. Phase 3: Add highlights and event-driven triggers.
4. Phase 4: Optimize performance (e.g., lazy-load tours).
5. Phase 5: Test edge cases (multi-tab, privacy tools, responsive layouts).

Operational Impact

Maintenance

• Short-Term:
  • Monitor for Filament version incompatibilities.
  • Patch locally if the package stagnates (e.g., fork and update DriverJS).
• Long-Term:
  • Deprecation Risk: Plan to replace if Filament adds native tour support or the package becomes obsolete.
  • Documentation: Maintain internal docs for tour configurations (PHP/JSON).
• Dependencies:
  • Pin driverjs version to avoid surprises.
  • Watch for Filament core changes affecting class names/selectors.

Support

• Debugging:
  • Use the CSS Selector Tool (enableCssSelector()) for troubleshooting.
  • Check browser console for DriverJS errors.
• User Feedback:
  • Gather analytics on tour completion rates (e.g., via Laravel events or frontend tracking).
  • Monitor support tickets for broken tours/highlights.
• Fallbacks:
  • Provide a "Skip Tour" button for users who disable JavaScript.
  • Log errors to Sentry/Laravel logs for proactive fixes.

Scaling

• Performance:
  • Tour Load: Tours are initialized via JavaScript; avoid heavy tours on critical paths.
  • Storage: localStorage is fine for "seen once" tracking, but avoid excessive data.
  • Lazy Loading: Load tours only on relevant routes (use ->route() or event triggers).
• Concurrency:
  • DriverJS handles single-user tours; no server-side scaling needed.
  • For multi-user tours (e.g., admin guides), ensure tour IDs are user-specific.
• Internationalization:
  • Tour titles/descriptions can use Laravel’s __() for translations.

Failure Modes

Ramp-Up

• Onboarding:
  • For Developers:
    • Document the PHP/JSON tour syntax and event system.
    • Provide examples for dynamic tours (e.g., user roles).
  • For End Users:
    • Add a "Tour Guide" link in the admin panel footer.
    • Use highlights to call out key features.
• Training:
  • Workshop: Demo tour creation (PHP vs. JSON) and event triggers.
  • Checklist: Validate tours work in dark/light modes and on mobile.
• Release Strategy:
  • Pilot: Roll out to a subset of users first (e.g., new users only).
  • Feedback Loop: Use Laravel Nova/filament notifications to gather user input.
  • A/B Testing: Compare tour completion rates vs. traditional tooltips.