Tutorials Laravel Package

Getting Started

• Install through Composer: composer require laravel-enso/tutorials. This package is part of the Enso ecosystem, so it assumes laravel-enso/enso (and its Vue frontend scaffolding) is already in place.
• Publish and run the package's migrations so the tutorials table exists: look for php artisan vendor:publish --tag=tutorials (or the enso:package:install flow Enso uses) and then php artisan migrate. Check database/migrations in the package source — the install command name can change between Enso minor versions.
• Look first at the package's src/ for the Tutorial model, its resource/controller, and the routes file. That is the contract you will build against: a tutorial is keyed to a route/page and holds an ordered set of steps.
• First use case: create a minimal tutorial row for one screen (e.g. /users) whose steps highlight nav elements so a new admin sees where to click. Drive it from a seeder using the Tutorial model rather than hand-inserting rows — this keeps the walk-through versioned with your code.
• Confirm the frontend side: the Vue component and wherever Enso mounts the tour trigger (usually a help/"?" button in the layout). If it is not wired up after install, that is where you look.

Implementation Patterns

• Seed tutorials alongside features. Treat tutorials like fixtures: define each tour in a dedicated seeder (TutorialsSeeder) with step data and run it from DatabaseSeeder. This makes onboarding tours reproducible across environments instead of manually entered in production.
• Route-scoped tours. One record per route/path is the natural pattern. When a page has multiple contexts (list vs. detail), match on the route name or path so the right tour loads. Fetch the applicable tutorial from a controller endpoint the frontend calls on page mount.
• Gate tours with permissions. Enso's permission system is the clean way to control who sees which tutorial. Wrap the tutorial endpoint in a permission/middleware and only return steps the current user can actually perform — otherwise you tour users through buttons that will 403.
• Step content as structured data. Store each step as { element, title, description, position, order }. When the underlying UI changes (selectors, labels), update the seeder and re-run it — treat the selectors as code, not content.
• Frontend wiring. Mount the tutorial component in your page layout and trigger it on first visit (e.g. localStorage flag) or via an explicit "Start tour" button. Enso's Vue layout typically exposes a slot where you can place this.
• Integration with the rest of Enso. Pair tutorials with laravel-enso/menus and the localization package so the tour text lives in the same translation strings as your UI, and the highlighted menu items match what the user actually sees.

Gotchas and Tips

• Selectors are brittle. Any CSS-class or data-attribute change in your UI silently breaks a step. Prefer stable data-* hooks and add a smoke checklist when refactoring screens with tours.
• Route matching edge cases. Parameterized routes (/users/{id}/edit) and cached route names can cause a tour to load or fail to load unexpectedly. Match on route name where possible and test on real URLs, not just /users.
• Permission caching. Enso caches permissions; if a tour "disappears" after a role change, clear caches (php artisan cache:clear / Enso's own cache commands) before assuming the tutorial package is at fault.
• Ordering and indexing. Step order must be deterministic. If the package stores an array/JSON blob, sort explicitly rather than relying on insertion order from the seeder — re-runs can shuffle it.
• Small package, low activity. With ~11 stars this is a lightly used, niche add-on. Pin the version in composer.json, and be ready to read the source rather than rely on docs — the README is minimal. Cross-check against the Enso version you run; APIs shift between Enso releases.
• Extension point. The cleanest extension is your own seeder + a thin controller wrapper that post-processes steps (localization, permission filtering) before handing off to the frontend component — rather than forking the package.
• Debugging a tour that won't show. Check three things in order: (1) the record exists and matches the current route, (2) the user has the required permission, (3) the frontend component is actually mounted on that page layout. Most "broken" tours are a missed mount, not bad data.