Mary Ui Starter Kit Laravel Package

Getting Started

This starter kit is a Laravel 13 application skeleton (Mary UI + Livewire), not a library you composer require into an existing app. Day one is:

git clone https://github.com/lauroguedes/mary-ui-starter-kit my-app
cd my-app && composer install && npm install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed   # 53 seeded accounts + roles/permissions
npm run dev & php artisan serve

Where to look first, in order:

1. routes/ and app/Livewire/ — the Mary UI screens (Users list is the reference implementation of every pattern in the kit).
2. database/seeders/ — the 53 accounts and role/permission graph are the fixture the demo relies on.
3. config/demo-mode.php (published from the new package) plus the DEMO_* block in .env.example.
4. tests/Feature/DemoSandboxTest.php — the canonical example of how the kit asserts that a feature is inert until enabled.

First use case: stand up a hosted demo. Set the demo flag on, run php artisan demo:doctor and fix anything it flags, point cron at php artisan schedule:run every minute, commit. The kit handles the scheduled reset, the rotating published password, login-form prefill, and the floating notice bar — you configure it, you don't build it.

If you only want the application scaffold, ignore everything demo-related: it is inert by default, no scope, no middleware behaviour, one unused nullable column.

Implementation Patterns

Kit-as-base vs. demo-as-package. v1.6.0 moved demo mode out to lauroguedes/laravel-demo-mode. Treat the demo package as a dependency you configure and the kit as your app. Any demo bug you hit belongs upstream; local patches will be overwritten. Pin the package version in composer.json — the kit's demo behaviour is now coupled to a package release cadence, not to the kit's.

Environment-driven presentation. Everything a visitor sees in the banner is DEMO_BANNER_*. Dressing the demo for a launch (different copy, different colour, different reset wording) is an .env change and a config cache clear, not a deploy. Keep those values out of committed .env and in your deploy platform's secret store if you're running multiple demo instances.

Sandbox scoping as a driver, not a mode. DEMO_SANDBOX=scoped is an opt-in strategy on the marked model (App\Models\User). Pattern:

• Mark the model with the package trait; the trait adds no scope and no hook unless the driver is scoped.
• Let the middleware resolve the visitor's sandbox id from the session and return immediately when the driver is anything else.
• Keep shared everything that is demonstration content rather than visitor content: roles, permissions, seeded sign-in accounts. Forking those breaks the demo for the next visitor.
• The clear button removes only the visitor's own rows; the cron reset rebuilds the world. Two separate lifecycles — don't try to make the button do a reset.

Validation across sandboxes. Because the scope is invisible to the query builder, unique:users,email sees every sandbox. Write registration validation with that in mind: a "this email is taken" message may refer to a row the visitor will never see. If you extend the kit with per-visitor entities, prefer application-level uniqueness checks you control over raw unique: rules, or accept the global namespace and word the error generically.

Reset schedule is the contract. The banner countdown is derived from the same cron expression the scheduler reads, so there is exactly one source of truth. Change the schedule in one place; never hardcode a "resets in N hours" string.

Testing pattern worth copying. DemoSandboxTest.php asserts inertness — that on an ordinary deployment the trait adds no scope, the column stays unused, and the middleware no-ops. Adopt this for any conditional feature: a test that the feature is off is more valuable than another test that it's on.

CI integration. php artisan demo:doctor exits non-zero on anything that would destroy data or publish a secret. Wire it into CI and into your pre-deploy script; it's a cheap guard against shipping a demo config to a real deployment.

Gotchas and Tips

The big one: demo mode deletes data on a schedule by design. demo:doctor will refuse to run against configurations it considers destructive, but it is a lint, not a safety interlock. Never enable it on an environment holding anything you can't reseed — the reset is the feature, not a bug.

Sandbox identity is session-bound. Logging out does not end a sandbox; a new browser or a cleared cookie jar gives you a new one. Expect "my test accounts vanished" reports from visitors who switched devices. The reset button is the documented way to get a clean slate — link to it, don't reimplement it.

Unique email errors leak across sandboxes. Two visitors cannot register the same address even though neither can see the other's row. If you're demoing multi-tenant behaviour, this contradicts the story on screen. Decide deliberately: accept it, or add a sandbox-aware lookup with a clearer message.

The notice bar lives in a shadow root. Application CSS will not reach it, and that is intentional — it renders identically here and in any other kit consuming the package. Style it through DEMO_BANNER_* only; trying to override from resources/css/app.css is a dead end.

Countdown fidelity. The bar will only promise a reset the scheduler can actually deliver. If it shows nothing, your cron expression and your scheduled task disagree — check the config, not the frontend.

Transitive majors in this release. Laravel 13.26 → 13.33 dragged guzzle 7 → 8, brick/math 0.18 → 1.0, and laravel/mcp 0.9 → 1.0. If you've added packages on top of this kit, run a full composer update --dry-run and your test suite before merging; guzzle and brick/math majors are the usual suspects for third-party breakage. laravel/mcp 0.9 → 1.0 is pre-1.0 churn regardless of the number.

Upgrading from 1.5.x. The hand-rolled demo is gone. If you customised it locally — banner markup, reset command, login prefill — that code no longer exists and your changes are lost. Port the customisation into DEMO_BANNER_* config or a package-level extension point, and add the new migration for the sandbox column. Verify with demo:doctor immediately after upgrading.

Debugging order for demo issues: demo:doctor → config('demo-mode.*') after config:clear → the scheduled task list (php artisan schedule:list) → the sandbox driver value. Almost every "the demo is broken" report resolves in the first two steps, and almost every one of those is a stale config cache.