Pawsome Mary Laravel Package

Getting Started

Pawsome Mary is a starter kit, not a library — you don't composer require it into an existing app. You scaffold a new project from it and then own the code outright. That distinction drives everything else below.

Minimal path:

# Via the Laravel installer (if the kit is registered) or directly:
laravel new my-app --using=pawsome-mary

# Or clone/copy the repo and:
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
npm install && npm run dev

First three places to look, in order:

1. routes/web.php + routes/auth.php — confirms which auth flows (OTP registration, passkey login) are wired and at what paths.
2. app/Livewire/ — the MaryUI-driven auth screens live here. This is where you'll spend most of your customization time.
3. config/ for passkeys and OTP — the two non-standard pieces. Confirm the relying-party ID (passkeys) and OTP expiry/length before touching anything else.

First real use case: spin up an authenticated dashboard with role-gated navigation in under an hour. Register with OTP, seed a couple of roles, log in with a passkey, and confirm a permission-gated route behaves correctly. If that loop works end to end, the kit is doing its job.

Because 0.5.2 is the first release, treat it as a greenfield scaffold you'll fork and maintain, not something you'll composer update. Pin your Laravel/Livewire/MaryUI versions on day one.

Implementation Patterns

MaryUI as your UI vocabulary. Every screen is composed from <x-…> MaryUI components sitting on DaisyUI/Tailwind classes. Rather than hand-rolling forms, follow the existing auth components' shape — x-form, x-input, x-button, x-card — so new screens inherit the same theming and validation display. When you need a new admin screen, copy an existing Livewire component's skeleton (property bag → rules() → save()) and swap the fields; that keeps you inside the kit's conventions instead of fighting them.

OTP registration flow. Registration is a two-phase interaction: collect identity → send code → verify. Customize it in the Livewire registration component plus the notification/Mailable that mints the code. A pattern that pays off:

// Keep issuance in one place so both resend and initial send share it
$code = $this->otpService->issue($user); // persists hash + expiry, sends notification

Store a hash of the code with an expires_at and an attempt counter, never the plaintext. Gate the "verify" step on a signed or session-scoped pending-user record so the unverified account isn't fully authenticated yet.

Permissions: seed early, gate consistently. If the kit ships Spatie's permission package, define roles/permissions in a seeder on day one and reference them via enum or constants rather than raw strings:

// database/seeders/RoleSeeder.php
Role::findOrCreate('admin');
Permission::findOrCreate('manage-users');

Then use @can in Blade, ->can() in policies, and middleware('can:manage-users') on routes — pick one primary enforcement layer (policies/middleware) and let Blade directives be cosmetic only. Don't sprinkle permission checks across controllers and views; you'll get drift.

Passkeys alongside passwords, not instead of them. The pragmatic integration is additive: leave the existing password (or OTP) login intact and register a passkey as a second credential on the profile/security screen. Feature-detect in the browser and hide the passkey button where unsupported rather than degrading the whole login form. Treat passkey registration as a post-login action so a broken WebAuthn ceremony never blocks account creation.

Composable workflow for a typical feature: Livewire component (state + validation) → action/service class (OTP issuance, passkey registration, role assignment) → policy/middleware (authorization) → Blade with MaryUI components → Pest/PHPUnit feature test hitting the route. The kit's own auth tests are your template for asserting OTP and passkey paths without real hardware (fake the WebAuthn assertion at the service boundary).

Gotchas and Tips

• It's a template, so "updating the package" means diffing upstream by hand. There's no clean upgrade path from 0.5.x to later versions while the kit is at 0.x. Fork deliberately, note the release you scaffolded from, and cherry-pick fixes rather than pulling wholesale.
• Version 0.5.2 as a "first release" is a signal. Early 0.x starter kits churn — component signatures, Livewire property names, route layouts. Don't build a large app on top before the kit stabilizes, or budget for rework.
• OTP in local development is the #1 time sink. Mail is easy to misconfigure (MAIL_MAILER=log means codes go to storage/logs/laravel.log, not your inbox). Consider a local escape hatch — log the code at debug level, or allow a fixed test code only when app()->isLocal(). Never let that branch survive into staging.
• Passkeys are origin-bound. WebAuthn relying-party ID and origin must match the actual host. localhost works for dev, but 127.0.0.1 vs localhost, HTTP vs HTTPS, and any proxy/APP_URL mismatch produce opaque browser errors. If passkeys fail silently, check APP_URL, session domain, and the RP config before the JS. Also remember passkeys require a secure context (HTTPS) outside local hostnames.
• MaryUI + DaisyUI theming is class-driven and easy to break. DaisyUI theme tokens (primary, base-100) come from your Tailwind config. Overriding brand colors means editing the theme, not the components — and custom classes on MaryUI components may be merged, not replaced. Check the rendered HTML when a class "doesn't apply."
• Permission and role caches go stale after seeding. Clear the Spatie cache after programmatic role changes (php artisan permission:cache-reset or the equivalent) or tests will mysteriously fail. Use RefreshDatabase plus re-seeding in tests.
• Keep authorization in one layer. The most common day-to-day bug in permission-based starter kits is a UI that hides a button while the route stays open. Every @can should have a matching server-side check.
• Extension points to prefer: custom Livewire components over editing the kit's auth components in place; a dedicated service class for OTP and passkey logic so you can swap the implementation; policies for anything beyond simple role checks. Editing shipped components directly is fine for a small app, but it makes upstream diffs painful later.
• Pin and document your stack versions (Laravel, Livewire, MaryUI, DaisyUI, Tailwind, the passkeys package) in the README. With a 0.x starter kit, reproducing the environment six months later is otherwise guesswork.