Laravel Int Laravel Package

Getting Started

1. Install and confirm discovery. composer require epigra/laravel-int. Check the package's composer.json for extra.laravel.providers / aliases. If they're absent (common in smaller packages), register the service provider and facade manually in config/app.php before assuming anything works. This is the single most common first-run failure.
2. Publish the config first. Run php artisan vendor:publish --provider="Epigra\Int\IntServiceProvider" (confirm the exact provider FQCN from the repo) and read the generated config/int.php end to end. Treat that file as the package's real documentation — for a package with no dependents and no ecosystem, the config keys and the README are your only sources of truth.
3. Read the source before the README. Clone the repo into vendor/epigra/laravel-int (or open it in your IDE) and skim src/. Look for: what the service provider binds into the container, what the facade proxies, whether it hooks into Laravel's translator or reimplements it, and whether it registers middleware. Ten minutes here prevents a day of guesswork later.
4. Pin down the locale source of truth. Decide up front whether locale lives in the session, a URL segment, a cookie, or a user column. The package will likely offer helpers for one or more of these; pick one and enforce it everywhere.
5. First use case — a working switch in under an hour. Set app.locale and app.fallback_locale, add a lang/{code} directory with two keys, add a /lang/{locale} route that writes to session and redirects back, and render {{ int('welcome.title') }} (or whatever the package's helper is) in a Blade view. Once that round-trips, you understand 80% of the package.

Implementation Patterns

Detection middleware. Put locale resolution in a single middleware ordered after StartSession and after auth if locale is user-scoped. Resolve in priority order: explicit request param → session → authenticated user's preference → Accept-Language negotiation → config('app.fallback_locale'). Write it once and never read locale anywhere else.

Route-level localization. Two viable shapes:

• Prefix-based: Route::group(['prefix' => '{locale}'], ...) with a whereIn constraint built from config('int.locales'). SEO-friendly, cache-friendly, but requires every route() call to pass the locale — consider a URL::defaults(['locale' => app()->getLocale()]) call in a middleware to avoid threading it through every view.
• Session-based: cleaner URLs, no route changes, but locale is invisible to crawlers and shared links don't carry language. Fine for authenticated apps, bad for marketing pages.

Language switcher as a component. A Blade component or Livewire component that renders available locales from config and posts to a single controller action. On switch: persist to session (and user record if logged in), then redirect()->back() with the previous URL preserved — not redirect('/'), which loses the user's place.

Config over DB. Keep the locale list in config/int.php, not a languages table. Locale sets change on deploy, not at runtime; a DB table forces a query per request or a cache layer you'll forget to invalidate.

Fallback chain for content. For model-level translations (product names, categories), the pattern that ages best is a translations relation with locale + value columns and an accessor that tries app()->getLocale() then falls back. If the package provides such a trait, use it; if not, don't force the package into that role — Laravel's own HasTranslations-style accessor is easier to reason about.

Validation and auth messages. Point users at lang/{code}/validation.php and lang/{code}/auth.php early. Most "the package is broken" reports are actually untranslated framework strings leaking through in a non-English locale.

Testing. Use $this->withSession(['locale' => 'tr'])->get(...) for session flows, and app()->setLocale('tr') in unit tests. Assert on rendered strings, not on package internals, so a version bump doesn't break your suite.

Gotchas and Tips

• config:cache and published config. If you publish config after running php artisan config:cache, your changes won't apply until you re-cache. This bites during initial setup constantly.
• Middleware ordering. A locale middleware placed before StartSession sees no session and silently falls back to the default — the symptom looks like "session isn't saving" when it's actually ordering. Check app/Http/Kernel.php or bootstrap/app.php.
• Route caching. Localized route groups with {locale} constraints work under route:cache, but closures in route files do not. Convert switcher routes to controller actions before deploying behind a cache.
• URL segment vs session conflict. If you support both, define precedence explicitly and document it. Otherwise a user who switches language then clicks a hardcoded localized link gets whiplash, and you'll chase "random locale resets" for weeks.
• Missing-key behavior. Laravel's translator returns the key itself when a translation is missing. Confirm the package doesn't swallow that and return empty strings instead — empty strings hide gaps in production and make review harder.
• Pluralization and gender. Laravel delegates plural forms to Symfony's PluralizationRules, keyed by locale. Turkish, Japanese, and Chinese have a single plural form; Arabic has six. If the package ships its own pluralizer, verify it against Laravel's before trusting it for these locales.
• Locale ≠ timezone ≠ currency. Don't let one config value drive all three. A Turkish-locale user in Germany may still want EUR. Pass currency explicitly.
• Don't translate slugs unless you also handle 404 fallbacks and redirects for every historical slug. Prefix-only localization is far cheaper to maintain.
• Extension points are thin — plan for it. With zero dependents, expect no plugin system. If you need custom resolution logic, wrap the package behind your own LocaleResolver interface rather than calling its helpers directly from controllers and views. That way, if the package goes unmaintained (a real risk at this size), swapping it out is a one-file change.
• Budget for maintenance. One maintainer, no downstream users, no issue history to mine. Pin the version in composer.json and add a smoke test that asserts your switcher round-trips — that test is your early-warning system for a breaking release.