Hej Laravel Package

Product Decisions This Supports

• Build vs. buy for social authentication. Hej supplies the redirect → provider → callback → user resolution plumbing on top of Laravel Socialite. The buy case is "standard OAuth social sign-in, done in days"; the build case only wins if you need provider behavior Socialite doesn't model.
• Roadmap: provider expansion as configuration, not engineering. The new allowed-providers config turns "add Apple / add a regional provider / disable a provider in staging" into a config PR rather than a code change. That shortens the lead time on market-entry and regional-launch roadmap items and moves the work from engineering to ops.
• Post-login routing as a product surface. Config-based redirects let you control where users land after auth without touching package internals — useful for whitelabel/multi-tenant deployments, campaign landing flows, and onboarding funnels that need to vary by environment or brand.
• Lower cost to extend the user profile. 4.0 removes $fillable from the shipped model and makes the controller the extension point. Adding fields (locale, referral source, job role) no longer means forking or patching a vendored model — a meaningful reduction in long-term maintenance cost.
• Governance and security posture. An explicit provider allowlist is a least-privilege control: you can prove which identity providers are enabled per environment, which is the kind of evidence security reviews and audit questionnaires ask for.
• Deprecation of Laravel 8 sets your platform floor. Dropping 8.x aligns this dependency with your Laravel upgrade roadmap; it becomes a forcing function (or a blocker) depending on where your app sits.

When to Consider This Package

Adopt when:

• You need conventional OAuth social sign-in (Google, GitHub, Apple, etc.) on a Laravel app and don't want to hand-roll routes, controllers, and callback handling.
• You want provider availability and post-login redirects managed declaratively per environment, ideally by someone who isn't a PHP developer.
• You expect to add profile fields: 4.0's removal of $fillable means you extend the controller instead of editing a vendored model.
• You are on Laravel 9+ and can take a major-version bump with a config migration.

Look elsewhere when:

• You need enterprise identity — SAML, OIDC, SCIM provisioning, MFA, passwordless, session/device management. That's Fortify, WorkOS, Auth0, or Cognito territory; Hej is not an identity platform.
• You're pinned to Laravel 8. 4.0 drops it — stay on 3.x or upgrade the framework first.
• You need per-provider scopes, token refresh, or provider-specific quirks beyond what Socialite exposes; you'll end up forking, which erases the buy argument.
• Your threat model requires a hardened, audited auth surface with a published security policy — evaluate maintenance cadence and CVE history before committing.

Upgrade considerations for 4.0 (breaking): republish and reconcile the config (redirects and allowed providers both moved into it), audit any code relying on mass assignment against the published model, and verify that previously working providers aren't silently denied by an un-updated allowlist. Treat the redirect setting as security-sensitive — validate it against open-redirect abuse.

How to Pitch It (Stakeholders)

For executives: This package is the "buy" half of a build-vs-buy decision on social login. It gives us standard sign-in with Google, Apple, and others without owning the OAuth plumbing. The 4.0 release makes provider rollout a configuration change instead of an engineering project, which is the part that matters commercially: entering a new market or enabling a new identity provider becomes a same-week ops task rather than a sprint. Cost is a config migration and a Laravel version floor, not a rewrite.

For engineering: 4.0 is a breaking major, scoped tightly. Three changes: Laravel 8 support is gone (9+ required); redirects and allowed providers move into the published config, so the config file must be republished and diffed rather than merged blindly; and the shipped model no longer declares $fillable, with the controller now the designated extension point. Practical impact — check for custom controllers extending the package's, check for mass-assignment calls against the user model, and check that the new allowlist doesn't lock out providers that were previously reachable by default. Redirect targets should be treated as untrusted input.

Recommendation: Adopt on Laravel 9+ projects where social login is a commodity feature. Pin 3.x if you're still on Laravel 8, and schedule the 4.0 upgrade alongside the framework bump with a config diff and an auth smoke test as the acceptance criteria. Reassess if requirements move toward SSO, MFA, or enterprise identity — at that point this package is the wrong layer and we should be evaluating an identity provider instead.