Laravel Keycloak Laravel Package

Technical Evaluation

What changed in v0.5.1: documentation only. No source code, no dependency, no signature changes. The release adds a README note under "Страница входа" (login page) explaining that when a default layout is registered for all pages in resources/js/app.ts, the package's Welcome page must be excluded by name:

layout: (name) => (name === 'Welcome' ? null : AppLayout)

and that setting layout: null inside the page component does not work, because Inertia re-applies the default layout.

Architecture fit. This is a Laravel package that ships auth-related UI — specifically an Inertia page named Welcome — plus backend wiring implied by the openssl requirement (signing, tokens, or encryption; the notes don't say which). Architecturally it sits at the intersection of three of the host app's layers: the service provider/container, the published frontend pages, and the app-wide Inertia bootstrapping in app.ts. The first two are conventional package territory. The third is not: the package's correct rendering depends on a line of code in the consumer's entrypoint, keyed on a string page name. That is a cross-cutting coupling, and v0.5.1 is the first time it is documented. Treat the doc note as a disclosure of an existing integration hazard rather than a new feature.

Integration feasibility. Mechanically straightforward: composer require, publish config/assets, register the layout exception. The real gate is the platform floor — PHP 8.4+ and Laravel 13. Both are aggressively leading-edge; a host still on Laravel 11/12 cannot adopt this at all, and Laravel 13 availability/support maturity should be confirmed before we commit. The openssl extension is ubiquitous but must be verified in the container image and CI matrix, because its absence is a boot-time hard failure, not a graceful degradation.

Technical risk.

• Versioning: 0.x. No API stability guarantee, and semver gives us no signal about which patch releases are safe.
• Silent-footgun class of change: the behavior in v0.5.1 already existed in prior versions — it was simply undocumented. Consumers on ≤0.5.0 who followed the README may have shipped a login page rendered inside an authenticated-style layout. Worth auditing any existing integration, not just upgrading.
• Name-based coupling: the fix hardcodes 'Welcome'. If the package renames the page, or the host renames/locale-switches it, the exception silently stops matching and the bug returns with no error.
• Downgrade of the escape hatch: layout: null being ineffective inside the page is counter-intuitive and will be re-discovered by every new engineer who touches this.
• Upgrade regression risk from v0.5.1 specifically: near zero, since only Markdown changed.

Key questions for the maintainer:

1. Why is Laravel 13 a hard floor — is the constraint ^13.0 or would ^12|^13 work? This single answer determines whether we can adopt now.
2. What is openssl used for, and what is the algorithm/key-management story?
3. Are the Inertia pages published into the host (forked, ours to edit) or served from the vendor directory (overwritten on upgrade)? This changes our remediation options for the layout issue entirely.
4. Is the page name Welcome part of the public contract? Can the layout exception be keyed on something sturdier (a route name, a layout property on the page, an exported constant)?
5. Which inertiajs/inertia-laravel and @inertiajs/vue3 (or React) versions are supported and tested?
6. Is there a 1.0 roadmap and a stated deprecation policy?

Integration Approach

Stack fit. Assumes a Laravel 13 host with Inertia + TypeScript/Vite and a persistent default layout (AppLayout). If our frontend registers layouts globally — which is the common Inertia pattern and the default in most starter kits — we will hit this. If we instead set layouts per-page, we are unaffected. Confirm which pattern our app uses before scoping anything; this is a five-minute check that determines whether the release is relevant to us at all.

Migration path.

1. Verify host prerequisites: PHP 8.4 in local, CI, and runtime images; ext-openssl enabled; Laravel 13 in composer.json.
2. composer require with an exact pin (e.g. 0.5.1, not ^0.5), publish config and any assets, committing published files to VCS so vendor overwrites are visible in diffs.
3. Register the layout exception in resources/js/app.ts using the documented resolver form, with an inline comment linking to the README section — this is the kind of line that gets "cleaned up" by someone who doesn't know why it's there.
4. Run any package migrations; smoke-test the full auth flow (login, logout, redirect-after-login, already-authenticated access to the login route).
5. Test with SSR enabled if we use it — the layout resolver runs server-side too, and a mismatch produces hydration noise rather than a clean error.

Compatibility. Pin the Inertia adapter versions explicitly and verify against the package's tested matrix rather than assuming. Validate that our Vite/TS build resolves the resolver signature; a typed layout function with a narrower signature than Inertia expects will fail typecheck, not runtime, which is the preferable failure but still a gate.

Sequencing.

• Phase 0 (spike, ~1 day): branch install, confirm the layout bug reproduces without the exception and disappears with it, and — critically — confirm the exception does not leak to other pages.
• Phase 1: integrate behind a feature flag on a non-production auth route set.
• Phase 2: staging validation of the login journey, including the "logged-in user visits /login" case.
• Phase 3: production rollout with a documented rollback (revert the app.ts line and the composer pin together — they must move as a unit).
• If an existing integration is already in place on ≤0.5.0, insert a Phase 0.5: audit the live login page for the sidebar-rendering symptom before doing anything else.

Operational Impact

Maintenance. Ongoing cost is low and mostly passive: a 0.x dependency with a narrow compatibility window that we pin and bump deliberately. The real maintenance item is the app.ts exception — an undocumented-in-code coupling that needs a comment and a test, or it will be removed by a future cleanup and regress silently. Budget a small amount of recurring effort for tracking README diffs, because this release demonstrates that behavioral requirements can be disclosed in documentation without a corresponding code change or version signal.

Support. Auth surfaces generate high-severity tickets, and the failure mode here is confusing before it is severe: the login page renders with an authenticated-looking side menu. That produces "am I logged in?" tickets, and — worth flagging to security — renders navigation chrome, route names, and possibly user-conditional UI to unauthenticated visitors. Low exploitability, poor optics, trivial to fix once recognized. The support runbook entry should be one line: "Login page shows the sidebar → check the layout resolver in app.ts." Note that this diagnostic only exists because of v0.5.1; before it, the same symptom would have been debugged from scratch.

Scaling. Negligible. Session/cookie auth, one page render, and a handful of openssl operations per login. No throughput or data-volume concerns; no new stateful component; nothing that changes our capacity model.

Failure modes, in rough order of likelihood:

1. Layout exception removed or broken by a refactor → sidebar returns on the login page. No error, no alert, caught only by visual QA.
2. Page renamed upstream on a future bump → same symptom, plus the exception line silently becomes dead code.
3. openssl missing from a new base image or CI runner → hard boot failure. Cheap to guard with a startup assertion.
4. Inertia major version changes the layout resolver contract → build or typecheck failure; detected early, fixed by re-reading the README.
5. Laravel 14 release strands us on an untested combination; the strict Laravel 13 requirement means we inherit the maintainer's upgrade cadence.
6. Upstream publishes pages into the vendor tree and an upgrade overwrites local customizations — verify publish semantics before customizing anything.

Ramp-up. One developer-day for an engineer already fluent in Inertia persistent layouts; two to three days otherwise, because the layout: null ineffectiveness is genuinely non-obvious and the docs only make sense after you've seen the resolver. Required prior knowledge: Laravel package auto-discovery and publishing, Inertia page/layout lifecycle, and Vite/TS entrypoint wiring. No PHP internals knowledge needed for the integration itself, though someone on the team should understand the openssl dependency before this touches production auth.

Recommendation. Low-risk release with an outsized informational payload: v0.5.1 is a docs patch that documents a pre-existing integration footgun rather than introducing one. Accept the upgrade (no code changed), apply the app.ts exception with a code comment and a visual regression check on the login route, and gate broader adoption on the Laravel 13 requirement and the page-name stability question.