Email Magic Link For Laravel Laravel Package

Product Decisions This Supports

• Multi-tenant / B2B invite flows become viable out of the box. The scope on invitations (e.g. invite(..., scope: 'workspace-7')) means one tenant re-inviting an address no longer cancels an invitation another tenant sent. This is the difference between "we can support agencies, resellers, and multi-workspace customers" and "we need to build our own invitation layer first."
• Build vs. buy tilts toward buy — and now covers branding, not just lifecycle. Invitation lifecycle (issue, supersede, revoke, accept, expiry, resend) is deceptively expensive to get right; so is making the credential mail and the sign-in screens look like our product. v0.36.0's mail_identity and ui.layout move both into configuration rather than custom code.
• Tenant-aware sign-in mail is now a config decision, not a build. mail_identity names a class implementing MailIdentity; the issuing request hands it the account, and it supplies the application name used in the link mail and code mail (subject, introduction, sign-off) and the line the mail opens with. That means a reseller or per-workspace product can greet the recipient by name and name the tenant in the from-line of the mail — a visible, sellable white-label surface that previously meant forking notifications.
• The auth screens can live inside our own application chrome. ui.layout names a Blade component of ours; the request, confirmation and code screens render inside it, receiving title as a prop and the card as the slot. Our font stack, theme, <head>, and navigation apply to sign-in as they do everywhere else — the difference between "a third-party auth page" and "our product."
• Graceful degradation is built in, which lowers the cost of being wrong. An exception from MailIdentity is reported and the mail falls back to the bundled name and greeting; a ui.layout value that resolves to no component is dropped, logged at warning, and the screens keep their own layout. Misconfiguration is a logged warning, not a broken sign-in flow or a 500 on the login page.
• Zero test churn on the mail class. The outgoing mail remains MagicLinkNotification, so existing assertions against that class need no change. This release is additive; there is no migration and no contract change, unlike v0.34.0.
• Roadmap enabler for enterprise and platform tiers. Tenant-isolated invitations are table stakes for SSO/SCIM-adjacent enterprise onboarding, per-workspace seat management, and customer-facing admin consoles ("manage pending invites for this workspace"). Brandable mail and host-layout screens are the same story told to the buyer's brand team rather than their security team.
• Unblocks cross-tenant product surfaces: partner/marketplace onboarding, per-client workspaces for agencies, per-org team management in a single deployment. The scope round-trips onto IssuedInvitation and AcceptedInvitation and into the acceptance view, so the UI can render tenant-aware context without extra lookups.
• Low-risk default path for existing single-tenant products. Unscoped invitations still supersede only other unscoped invitations, and an unscoped revoke() still withdraws across all scopes. Without mail_identity and ui.layout, mail names app.name and opens with the bundled greeting, and the screens keep their own layout — identical to today.
• Upgrade cost remains small but must be scheduled. v0.34.0 shipped a nullable scope column migration and added a trailing ?string $scope = null to the two invitation contracts (breaking only for classes outside the package that implement InvitationStore or InvitationIssuer). v0.36.0 adds no schema change, but raises the documented WireKit floor to 2.68.0 — verify our wirekit/* constraint before upgrading, and expect older WireKit to render the screens with the pre-fix defects the package documents. Triage as a one-ticket engineering task, not a roadmap item.

When to Consider This Package

Adopt when:

• The product is Laravel/PHP and invitations are a real workflow (team/workspace invites, not just a one-off magic link).
• You are multi-tenant, or expect to be — scoped invitations are the reason to look now rather than later.
• You want the credential mail and sign-in screens to carry your brand or a tenant's brand without maintaining a fork: mail_identity for the mail's name and greeting, ui.layout for rendering inside your own Blade layout.
• You are selling to agencies, resellers, or multi-workspace customers where "the login email names their workspace and greets the user by name" is part of the pitch.
• You want supersede/revoke semantics (re-inviting invalidates stale invites) without owning that logic, and you want them to behave correctly per tenant.
• You are prepared to track a pre-1.0 package: v0.34.0 already contained a contract-level breaking change, so pin versions and budget for periodic upgrade tickets.
• You can run a schema migration and absorb a nullable column on the invitations table.

Look elsewhere or build thin when:

• The app is not Laravel, or you need invitation logic decoupled from the framework.
• You have custom InvitationStore / InvitationIssuer implementations — those classes must carry the ?string $scope = null parameter or PHP will refuse them. Audit before upgrading past v0.34.0.
• You already run a branded auth stack (custom controllers, a design-system login, or a third-party IdP-hosted flow). ui.layout helps only if these WireKit screens are the screens users actually see; otherwise you are pulling in presentation surface you won't use.
• You need per-tenant branding beyond name and greeting line — logos, per-tenant colors, localized copy per market. The MailIdentity contract covers the application name and opening line, not a full templating layer.
• Requirements run well beyond invitations: complex RBAC, SCIM provisioning, org-level policy enforcement, audit-grade compliance trails. This package is a focused primitive, not an identity platform.
• You need a stable, versioned public API surface (1.0+) with deprecation guarantees — not yet the case.
• Invitations are a single hard-coded flow that a 50-line controller already handles; the dependency isn't earning its keep.

How to Pitch It (Stakeholders)

For executives: This library handles user invitations and sign-in for our Laravel application. Two capability jumps matter commercially. First, invitations can be tagged to the tenant that sent them, so two customers inviting the same email address no longer interfere — a prerequisite for selling to multi-workspace and agency-style customers. Second, in the latest release the sign-in email can name the tenant and greet the recipient by name, and the sign-in screens can render inside our own site layout, so sign-in looks like our product (or a partner's) rather than a generic auth page. Both are configuration, not custom builds, and both fail safe: if a setting is wrong, the mail and screens fall back to today's behavior and we get a logged warning rather than a broken login. Cost is one short engineering ticket — a database migration from the prior release, plus confirming our UI library version meets the newly documented minimum. Behavior for current single-tenant usage is unchanged.

For engineering: v0.36.0 is additive — no migration, no contract change. mail_identity names a class implementing the new MailIdentity contract; the credential-issuing request passes it the account, and it returns the application name used in the link and code mails' subject/introduction/sign-off plus the mail's opening line. Exceptions are reported, and the mail falls back to the bundled name and greeting. The mailable remains MagicLinkNotification, so existing assertions hold. ui.layout names a host Blade component; the request, confirmation and code screens render inside it with title as a prop and the card as the slot; an unresolvable name is dropped and logged at warning with the screens falling back to their own layout. The documented WireKit floor is now 2.68.0 (reflected in composer suggest); older WireKit still renders but without the fixes enumerated alongside the floor — check our constraint before upgrading. Still outstanding from v0.34.0: (1) grep for classes implementing InvitationStore/InvitationIssuer and add the trailing ?string $scope = null — the only breaking surface; (2) run the included migration for the nullable scope column before enabling scoped behavior; (3) pin the version — we are on a pre-1.0 package that has already shipped one contract-level break.

Recommendation: Upgrade to v0.36.0 for hygiene and to pick up configurable mail identity and host-layout screens; adopt scope and mail_identity together on the first workspace-based flow, since tenant-scoped invitations and tenant-named mail ship the same customer story. Do the WireKit constraint check in the same ticket.