Block Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish the config: php artisan vendor:publish --tag=<package>-config. In 3.0.x the translation delivery endpoint is driven entirely from that config, so read it top to bottom before writing any code — the host/domain key is the first thing to locate.
• Confirm the service provider is auto-discovered (php artisan about or php artisan route:list --path=translations). If the package registers routes, you should see them bound to the main app domain until you change the config.
• For the 3.0.1 custom-domain feature, the first use case is: point a subdomain such as translations.example.com at the app, set the domain key (typically config('<package>.domain') or the equivalent env var like <PACKAGE>_DOMAIN), then php artisan config:clear && php artisan route:clear and hit the endpoint with curl -H "Host: translations.example.com" https://your-app/... to verify routing rather than guessing from the browser.
• Leave the domain key null locally so the routes stay on localhost/*.test; only set it in staging and production env files.

Implementation Patterns

• Environment-scoped domain config. Keep the domain in .env per environment (TRANSLATIONS_DOMAIN=translations.example.com) and never hardcode it in config/. Local and CI should resolve to null, which usually means "serve on the default host."
• Separate route group / middleware. Treat the translation domain as its own surface: its own middleware stack (no session, no CSRF, no auth unless the endpoint must be protected), its own rate limiter, and cache headers. This is also where you'd add throttle: and a CORS middleware if a JS front end consumes the JSON.
• CDN in front of the domain. Because translations are read-mostly, put Cloudflare/Fastly in front of the custom domain and rely on the package's cache/ETag behaviour. Invalidate by version tag or by bumping the cache key when translations change, not by purging per-request.
• Consumption patterns. Server-side, prefer the normal __()/@lang helpers; use the HTTP endpoint only for clients that can't read PHP files (mobile, standalone SPA). For SPAs, fetch once at boot into an i18n store and key off the locale segment rather than refetching per component.
• Multi-tenant / multi-brand. The domain setting is process-wide config, so a per-tenant domain needs either a resolver in a service provider (read host, map to tenant, set config before routes resolve) or one app instance per tenant. Resolve early — in boot(), not in a middleware that runs after route matching.
• Fallback behaviour. Always define fallback_locale explicitly and test a key that only exists in the fallback locale; missing-key handling differs between the file driver and the HTTP endpoint.

Gotchas and Tips

• Config and route caching are the #1 source of "my domain change did nothing." php artisan config:clear, route:clear, and on Octane php artisan octane:reload. Config read at boot is not re-read per request.
• Scheme/host mismatch behind a proxy. If the domain renders as http:// or the wrong host, set TrustProxies correctly (* or your LB CIDRs) — the package builds URLs from the request host and forwarded headers.
• www. and trailing-dot hosts are distinct route hosts. Pick one canonical form, redirect the other at the web server, and don't expect the package to normalise it.
• Route name collisions. If the package registers named routes and your app already defines the same path on the main domain, route:list will show duplicates and route() may resolve to the wrong one. Namespace or rename via config where supported.
• CORS preflight. A custom domain means a different origin for browser clients; a 200 on GET with a 403 on OPTIONS is a missing preflight handler, not a package bug.
• TLS/DNS is yours, not the package's. Provision the certificate for the new hostname first, otherwise you'll debug a routing problem that is actually a handshake failure.
• Upgrading from 3.0.0 → 3.0.1: treat it as a patch — no breaking change expected. Still, republish and diff the config (vendor:publish --force into a temp path, then compare) since new config keys in patch releases are commonly added without a migration path. Clear caches after every deploy that touches config.
• Debugging checklist: php artisan route:list --path=<path> -v (confirms host binding), curl -H "Host: ..." against the app directly to bypass DNS/CDN, then curl against the public domain to confirm the edge layer. If those disagree, the problem is DNS/CDN, not Laravel.
• Extension points: middleware on the package route group, the config's cache/store driver, and (in most such packages) a translation loader binding are the three safe places to hook in. Prefer those over subclassing internals, which are the most likely thing to move in a 4.0.