Filament Tour Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Lightweight & Non-Intrusive: Leverages DriverJS (a battle-tested library for guided tours) without requiring major architectural changes. Integrates seamlessly into Filament’s plugin system, maintaining separation of concerns.
  • Filament-Specific: Designed explicitly for Filament (v2/v3/v4), reducing cross-cutting concerns with other Laravel components.
  • Configurable: Centralized settings (e.g., only_visible_once, tour_prefix_id) allow customization without core logic modifications.
  • Event-Driven: Likely hooks into Filament’s lifecycle (e.g., panel initialization), enabling controlled tour triggers.

• Cons:

  • Tight Coupling to Filament: Not reusable outside Filament panels, limiting flexibility if the application later adopts a non-Filament UI layer.
  • DriverJS Dependency: Adds a frontend dependency (JavaScript/CSS) that must be managed alongside Filament’s assets (e.g., Vite/Mix).
  • Storage-Dependent: Relies on localStorage for "only visible once" logic, which may conflict with SSO or privacy-compliant storage solutions.

Integration Feasibility

• Low Risk: Installation is straightforward (Composer + plugin registration), and the package follows Filament’s conventions (e.g., Panel integration).
• Frontend Assets: Requires ensuring DriverJS CSS/JS are properly bundled (check Filament’s asset pipeline compatibility).
• Database Migrations: Optional but recommended for tracking tour completion (if only_visible_once is enabled).

Technical Risk

• Frontend Conflicts: Potential CSS/JS clashes with existing Filament plugins or custom scripts (e.g., overlapping highlights, conflicting event listeners).
• Performance: DriverJS adds ~50KB JS/CSS; impact negligible for most applications but worth profiling in high-traffic panels.
• LocalStorage Quirks: May not work as expected in private/incognito modes or with ad blockers stripping storage access.
• Filament Version Lock: Hard dependency on Filament versions (e.g., v4.x only works with this package’s v4.x branch).

Key Questions

1. Filament Version Strategy:
   • Is the team locked into a specific Filament version, or is multi-version support needed?
   • How will downgrades/upgrades be handled if Filament releases breaking changes?
2. Tour Customization Needs:
   • Are there complex tour flows (e.g., conditional steps, dynamic content) that require extending DriverJS beyond the package’s defaults?
3. Asset Management:
   • How are Filament’s assets (JS/CSS) currently bundled (Vite, Laravel Mix)? Will DriverJS need manual inclusion?
4. Tracking Requirements:
   • Beyond localStorage, is analytics or server-side tracking of tour completion needed (e.g., for A/B testing)?
5. Accessibility:
   • Has the package been tested with screen readers/keyboard navigation? Are there ARIA attributes or fallbacks for non-JS users?
6. Localization:
   • Are tour steps translatable, or will hardcoded text require overrides?

Integration Approach

Stack Fit

• Backend (Laravel/PHP):
  • Plugin-Based: Fits Filament’s plugin ecosystem natively. No backend logic changes required beyond plugin registration.
  • Config-Driven: Centralized settings (e.g., only_visible_once) can be managed via Laravel config or environment variables.
• Frontend (JavaScript):
  • DriverJS: Requires compatibility with Filament’s asset pipeline. If using Vite, ensure DriverJS is either:
    • Auto-included via Filament’s resources/js or
    • Manually imported in a Filament-specific JS file (e.g., resources/js/filament/tour.js).
  • CSS Conflicts: Test for overlapping styles with Filament’s Tailwind/Alpine components.

Migration Path

1. Pre-Integration:
   • Audit Filament version compatibility (e.g., ensure Filament v4.x is used for this package).
   • Verify asset pipeline (Vite/Mix) can handle DriverJS without conflicts.
2. Installation:

   composer require viezel/filament-tour
   php artisan vendor:publish --tag="filament-tour-config"
   php artisan vendor:publish --tag="filament-tour-views"
   php artisan vendor:publish --tag="filament-tour-migrations"  # Optional
   

3. Plugin Registration:
   • Add to Panel configuration:

     ->plugins([FilamentTourPlugin::make()->onlyVisibleOnce(fn() => app()->isProduction())])
     

4. Post-Integration:
   • Test in staging with real users to validate localStorage behavior and tour flow.
   • Monitor for frontend errors (e.g., DriverJS initialization failures).

Compatibility

• Filament Versions: Strictly tied to Filament v2/v3/v4. Avoid mixing versions (e.g., don’t use v4 package with v3 Filament).
• PHP/Laravel: No direct dependencies beyond Filament’s requirements (PHP 8.0+, Laravel 9+ for v4).
• Browser Support: DriverJS supports modern browsers; test edge cases (e.g., IE11 if still required).
• Filament Plugins: Potential conflicts with other plugins using similar frontend patterns (e.g., tooltips, modals). Test in isolation.

Sequencing

1. Phase 1: Install and configure the package in a non-production environment.
2. Phase 2: Implement a basic tour (e.g., highlight a single panel component) and validate the flow.
3. Phase 3: Extend with custom steps or conditional logic if needed (may require DriverJS overrides).
4. Phase 4: Deploy to production with monitoring for frontend errors.
5. Phase 5: Iterate based on user feedback (e.g., adjust only_visible_once logic).

Operational Impact

Maintenance

• Low Effort:
  • Updates can be handled via Composer (composer update viezel/filament-tour).
  • Configuration changes are centralized in config/filament-tour.php.
• Dependency Risks:
  • DriverJS updates may introduce breaking changes (monitor the DriverJS repo).
  • Filament major version upgrades may require package updates.

Support

• Debugging:
  • Frontend issues (e.g., tours not showing) may require inspecting DriverJS console logs.
  • Backend issues (e.g., localStorage failures) can be diagnosed via Laravel logs.
• User Feedback:
  • Track completion rates (if using migrations) to identify drop-off points in tours.
  • Monitor support tickets for common pain points (e.g., tours appearing unexpectedly).

Scaling

• Performance:
  • DriverJS is lightweight; no significant scaling concerns for typical Filament panels.
  • For high-traffic panels, test tour initialization time (e.g., avoid blocking critical rendering).
• Database Impact:
  • If using migrations, ensure the tours table scales with user growth (indexes on user_id if querying).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time Estimate: 1–2 hours for initial setup; additional time for customization.
  • Documentation: Package README is sufficient, but internal docs should cover:
    • Asset pipeline setup (Vite/Mix).
    • Custom tour step examples.
    • Debugging tips (e.g., DriverJS console logs).
• User Training:
  • Admin Users: Train on how to edit tour steps (may require extending the package).
  • End Users: Minimal training needed; tours are self-guided.
• Testing Checklist:
  • Tour appears in all target panels.
  • only_visible_once works as expected (test with incognito mode).
  • No CSS/JS conflicts with existing Filament plugins.
  • Tour steps are accessible (keyboard, screen reader).
  • Performance impact is negligible (Lighthouse audit).