Weave Code
Tutorials Laravel Package
guava/tutorials
Guava Tutorials is a Laravel package for adding in-app tutorials and guided onboarding flows to your application. Define steps, target users, and track progress through a simple, flexible API, helping new users learn features without leaving your app. It keeps tutorial content organized and easy to...
At a glance
Frequently asked questions about Tutorials
- How do I install guava/tutorials in a Laravel application?
- Install it with Composer using composer require guava/tutorials, then publish the package assets and run migrations so the tutorial and progress tables exist. The package ships a service provider plus publishable config, views, language files, and migrations, so the setup follows the conventional Laravel package install path. After publishing, define a tutorial in code and render it on one authenticated Blade page to confirm the loop works end to end. Plan a short spike rather than assuming the install alone delivers a finished feature.
- Does guava/tutorials require Filament or Livewire?
- The package is described as a native fit for a Blade-rendered Laravel monolith, but the published material does not explicitly confirm whether Filament or Livewire is a hard dependency. Because dragging an admin-panel stack onto customer-facing pages would add significant collateral integration cost, verify this in composer.json and the resolved lock file before committing. Answer this during the spike, ahead of any content authoring work. If the dependency surface is clean, integration stays small; if not, budget for isolating it.
- Which Laravel and PHP versions does guava/tutorials support?
- The package is at version 1.1.0 and follows standard Laravel package conventions, but the supported Laravel and PHP version ranges are not spelled out in the overview material. Check the require and require-dev blocks in composer.json, then run the test suite against your application's framework version during the spike. Pin the version you validate so an upstream minor release does not silently change behavior. This matters more than usual for a low-maturity, single-maintainer package.
- How do I define a multi-step tutorial with the fluent PHP API?
- Tutorials are declared in code through a fluent PHP API, where each tour is a set of ordered steps with action payloads and target information. Definitions are JSON-serializable so the front end can render them without a custom API layer. Keep definitions in dedicated classes or a registry rather than scattering them through controllers, and avoid embedding closures in definitions that get cached or persisted. That structure keeps tutorial content organized and easy to maintain as the number of tours grows.
- How does element targeting and highlighting work in guava/tutorials?
- Steps target elements on the current page, and the package renders a highlight plus tooltip overlay so users move through the walkthrough without leaving the page. Targeting is selector-based, which means overlay breakage is silent: refactor a page and the highlight simply highlights nothing. Mitigate with a stable convention such as data-tutorial attributes, a CI assertion that every configured target exists in the rendered DOM, and a skip-if-missing guard in your own boundary code. No package can catch selector drift for you.
- Can I track per-user progress and let users resume or dismiss a tutorial?
- Yes. The package stores progress records per user and supports resuming an in-progress tour and dismissing one entirely, so first-run onboarding and feature announcements behave sensibly across sessions. The package owns the schema, step ordering, publish controls, and overlay rendering. It does not own audience targeting, funnel analytics, or A/B assignment, so those remain product surfaces you build on top of it. Query progress through your own boundary rather than vendor models directly.
- Can I customize the tutorial overlay views and styling?
- Config and views are publishable, so you can override the markup and adjust behavior without forking the package. The open question is asset delivery: whether CSS and JS ship pre-built or require a Vite build. That single fact decides whether theming is a config edit or a CSS fork, and therefore whether the visual layer is a two-day or two-week line item. Confirm the asset model in the spike before promising a design.
- Does guava/tutorials work with config:cache and Laravel Octane?
- Version 1.1.0 added Closure support to action property types, and closures are not serializable. If a closure-bearing tutorial definition lands in a cached config array or a database column, config:cache can fail or silently drop it, and Octane's long-lived workers can hold stale bindings across deploys. Treat this as a hard gate: exercise config:cache and an Octane-style long-running worker in the spike, not on launch day. Keep definitions closure-free when they are cached or persisted.
- How do I handle translations and localization for tutorial content?
- The package ships publishable language files, and Persian is present with an RTL alignment fix shipped as a bug fix in a minor release. Per-locale key completeness is undocumented, and missing keys render as raw keys to users, which is a very visible failure. Publish the language files, diff every locale against the base set, and add a test that fails on missing keys. Own the translation gap rather than assuming coverage.
- Is guava/tutorials production-ready, and what should I watch for long term?
- It is a single-maintainer agency package at version 1.1.0 with effectively zero dependents, no stated SLA, and no commercial support path. That does not disqualify it, but it means naming an internal owner, reviewing releases quarterly with a smoke test, and keeping it off business-critical surfaces without a fallback. Wrap it behind a thin internal boundary, such as a TutorialRegistry that answers which tutorial a user should see right now, so Blade components, completion endpoints, and analytics never touch vendor classes. That keeps exit cost bounded by design, and it is also why a lighter-weight build-your-own or alternative approach stays viable if the dependency disappoints.
Weaver
How can I help you explore Laravel packages today?