Laravel Keycloak Laravel Package

Getting Started

• Confirm the runtime before installing. The package requires PHP 8.4+ with the openssl extension and Laravel 13. Verify with php -v and php -m | grep openssl; a missing extension shows up as a confusing boot-time failure rather than a Composer error.
• Install and publish. Pull the package through Composer, then run its publish/install command as documented in the README. Publishing is what puts the login page component and its supporting assets into your app, where you own and can edit them.
• Read the README section "Страница входа" first. It is the part that changes most often and the part you will actually touch — everything else is standard Laravel wiring.
• Check resources/js/app.ts before you look at the page itself. If you set a default layout for all pages there (the common layout: AppLayout or a resolver returning AppLayout unconditionally), that default is what your published login page will render inside.
• First use case: publish the login page, exclude it from the default layout, then load /login and confirm it renders full-screen without the sidebar. That one loop exercises install, asset publishing, and the Inertia layout contract.

Implementation Patterns

Exclude by name in the layout resolver, not in the page. As of v0.5.1 the documented pattern is:

// resources/js/app.ts
layout: (name) => (name === 'Welcome' ? null : AppLayout)

Use this when your app sets a layout globally for every page and the published login page must not inherit it. It keeps the global default for the rest of the app while punching a single hole for the auth screen.

Prefer the global-resolver-with-exclusions approach if most pages share a layout. It scales better than annotating every page: one list of exceptions in app.ts versus a layout property on dozens of components. Grow the exception list (name === 'Welcome' || name === 'Auth/Login') rather than scattering per-page overrides.

Verify the resolved name before writing the comparison. Inertia derives name from the component path your resolver produces, so the string in the comparison must match exactly what your setup emits. Log it once (console.log(name) in the resolver) and copy the value; do not guess from the filename.

Keep published components in version control and diff on upgrade. Because the login page lands in your app as source you own, upgrades do not overwrite it — which is good for customization and bad for silently missing fixes. After bumping the package, re-publish to a scratch directory or check the changelog and diff manually before deciding whether to touch your copy.

Treat auth-flow customization as app code, not package config. Redirect targets, extra fields, branding, and validation messaging belong in your published copy and your own form request/controller layer. This keeps the package upgrade surface small: you re-pull only when the upstream page gains a fix you want.

Gotchas and Tips

• layout: null inside the page does not work. This is the headline of v0.5.1. Inertia substitutes the default layout for a page that declares layout: null, so the sidebar you were trying to remove comes right back. You must exclude the page by name in resources/js/app.ts instead. If you have been debugging a phantom layout on the login screen, stop editing the page component.
• Exact string matching is brittle. name === 'Welcome' fails silently — no error, just the wrong layout — if your resolver produces Pages/Welcome, Auth/Login, or anything else. A silently-failing layout comparison is worth a defensive helper that normalizes case and path prefix.
• v0.5.1 is documentation-only. The package code is unchanged; there is nothing to reinstall for a fix. The only action item is applying the resolver exclusion if your app.ts sets a global layout.
• Version constraints are tight and intentional. PHP 8.4 and Laravel 13 are both recent; on shared hosting or an older base image the install will fail at the Composer level. Pin your CI image to match so the requirement surfaces early rather than in a deploy.
• Missing openssl fails late and cryptically. It is not a Composer platform requirement in most setups, so installs succeed and the failure appears at runtime during encryption/signing. Add the check to your provisioning script.
• Extension point for layout policy: the resolver function in app.ts is the single place to express "which pages are chromeless." Keep it declarative and centralized — a const CHROMELESS = new Set([...]) next to it makes the intent obvious and the additions reviewable in a diff.
• When something looks wrong, inspect the Inertia page object first. The component name and props shown in your devtools/Vue panel tell you immediately whether the resolver is matching, which is faster than reasoning about the Blade root template.