Laravel Compass Laravel Package

Getting Started

• Install with composer require (dev-only if you're just evaluating), then check whether the service provider is auto-discovered; if not, register it in config/app.php. Publish any config/assets (php artisan vendor:publish --provider=...) and read the published config top to bottom — for this package the domain/host resolution keys are the whole game.
• Look first at, in order: the README's domain section, the package config file, and the class that performs host→domain→tenant resolution (usually a resolver or middleware). The v1.2.1 change (#162) lives there: when a variable domain (placeholder/wildcard pattern such as {tenant}.example.com) is in play, the raw request host is now accepted as a fallback domain. Understand that branch before wiring anything else.
• First use case: one Laravel app serving a central/root host plus per-tenant (or per-site) hosts, resolved from the incoming request hostname. Get a single hard-coded domain resolving end-to-end (request → resolved domain → tenant/context bound → route/controller sees the right context) before adding variable domains.
• Local sanity check: add a host entry (/etc/hosts, or use Herd/Valet wildcards) for a test host, hit a route, and dump the resolved domain to confirm the pipeline. Then repeat via a variable domain and via the new host-fallback path.

Implementation Patterns

• Two-tier domain definitions. Keep an explicit list of known domains (exact matches, deterministic, cheap) separate from variable/pattern domains. Exact lookup should always win; the pattern matcher is the fallback layer, and the request host fallback introduced in v1.2.1 is the last resort. Write your resolution order down and test each tier independently.
• Treat the host fallback as an explicit opt-in-ish behaviour. It is most useful for hosts that are legitimately "the same site" as a variable domain — e.g. the bare/apex host or www. variant that doesn't fit the {tenant}.example.com pattern. If you don't want a misconfigured variable domain to quietly resolve to whatever host the request came in on, constrain it (allowlist central/root hosts, or keep a canonical-host map) rather than relying on the pattern to fail closed.
• Route organisation. Group tenant/site routes behind the resolution middleware and keep central routes (marketing, signup, webhooks, health checks) on a plain, non-resolving group. Webhooks and payment callbacks are the classic breakage: they arrive on arbitrary hosts, so exclude them from host-based resolution.
• Persist resolution for the request, not the app. Resolve once per request in middleware and stash the result (request attributes or a scoped container binding) so controllers, Blade, jobs dispatched in-request, and URL generation all read a single value. Avoid re-querying the domain table from multiple places.
• Cache the domain map. Domain→tenant lookups are on every request; cache the mapping keyed by host and bust it in the model's saved/deleted events (and on tenant rename/domain change). Don't cache the fallback decision — it depends on the incoming host.
• Testing. Laravel's HTTP tests let you drive arbitrary hosts: $this->get('http://acme.example.com/dashboard'). Build a small data provider covering exact domain, variable domain, host fallback, unknown host (should 404/abort), and central host. Assert the resolved tenant/domain, not just the status code — the new fallback is exactly the kind of thing that returns 200 with the wrong context.
• Console/queue context. Host-based resolution only exists during HTTP. For artisan commands and queued jobs, set context explicitly (tenant:run, job middleware, or a queued "current tenant" id) — don't assume the resolver will fill it in.

Gotchas and Tips

• Host strings are messier than they look. Normalise before matching: lowercase, strip the port, strip a trailing dot, and decide how to treat www. (usually strip or map it, because otherwise www.x.com and x.com resolve differently). Compare against $request->getHost(), not the raw Host header.
• Proxies and load balancers. Behind a proxy, getHost() may be the internal hostname. Configure TrustProxies so X-Forwarded-Host is honoured — otherwise every request falls through to whatever the fallback does, and with v1.2.1's host fallback that can mean requests silently resolving to an unintended site instead of failing.
• APP_URL vs. the request host. Route/URL generation and redirects should use the resolved domain's scheme and host, not APP_URL. Mixing them produces cross-domain redirect loops and broken asset URLs, especially with HTTPS termination at the proxy (URL::forceScheme).
• Sessions and cookies. Session/auth cookies are host-scoped. If tenants live on sibling subdomains and you want shared auth, set the cookie domain explicitly (and understand the security trade-off); if not, expect separate logins per host. The host fallback can make this confusing when two hosts share one tenant — the tenant is the same, the cookie jar is not.
• Local dev. *.localhost resolution varies by OS/browser, and Valet/Herd/Docker setups rewrite hosts. Test the variable-domain and fallback paths with the same host strings you use in production, or you'll debug the wrong layer.
• Debugging order. (1) what does $request->getHost() actually return, (2) does it hit an exact domain, (3) does it match a variable pattern, (4) did the new host fallback fire? Log the resolved domain and which tier matched — a debug flag on the resolver pays for itself the first time a fallback silently kicks in.
• Extension points. Prefer a custom resolver/pattern strategy or a Domain model hook over forking the resolution middleware; and keep domain creation in one service so cache invalidation and validation (uniqueness, no overlap with existing patterns) happen in one place.
• On this release specifically: v1.2.1 is one behavioural change plus a large batch of dependency bumps (Vue/sass/ws/lodash/ssri etc.). Those look like the repo's docs/front-end toolchain — including several security advisories (ws, browserslist, lodash, url-parse) — so they carry no action for a PHP-only consumer. The thing to actually regression-test is domain resolution: re-run your suite against hosts that previously 404'd, since they may now resolve via the host fallback.