Common Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel-lang/common
   

   Add the service provider to config/app.php under providers:

   LaravelLang\Common\CommonServiceProvider::class,
   

2. Publish Config:

   php artisan vendor:publish --provider="LaravelLang\Common\CommonServiceProvider" --tag="config"
   

   This generates config/lang.php with default settings.

3. First Use Case: Load a language pack (e.g., en or es) in AppServiceProvider@boot:

   use LaravelLang\Common\Facades\Lang;
   
   public function boot()
   {
       Lang::load('en'); // Load English pack
   }
   

   Use translations in Blade:

   {{ __('messages.welcome') }}
   

Implementation Patterns

Core Workflows

1. Dynamic Language Switching: Detect user locale (e.g., via app()->getLocale()) and load packs dynamically:

   Lang::load(app()->getLocale());
   

2. Fallback Chains: Configure fallback locales in config/lang.php:

   'fallbacks' => [
       'es' => ['en'],
       'fr' => ['en'],
   ],
   

   Then use Lang::get() with fallbacks:

   __('messages.hello', [], 'es'); // Falls back to 'en' if 'es' key missing
   

3. Partial Packs: Load only specific language files (e.g., validation.php):

   Lang::load('en', ['validation']);
   

Integration Tips

• API Responses: Set locale per request in middleware:

  public function handle($request, Closure $next)
  {
      app()->setLocale($request->header('Accept-Language'));
      Lang::load(app()->getLocale());
      return $next($request);
  }
  

• Admin Panels: Use Lang::getAvailableLocales() to populate a language selector:

  <select>
      @foreach (Lang::getAvailableLocales() as $locale)
          <option value="{{ $locale }}">{{ $locale }}</option>
      @endforeach
  </select>
  

• Testing: Mock translations in tests:

  Lang::fake([
      'en' => ['messages.welcome' => 'Test Welcome'],
  ]);
  

Gotchas and Tips

Pitfalls

1. Caching Issues: Clear config cache after publishing lang.php:

   php artisan config:clear
   

   Or disable caching in config/lang.php:

   'cache' => false,
   

2. Missing Packs: Ensure packs are installed via composer require (e.g., laravel-lang/english). Verify with:

   Lang::hasPack('en'); // Returns bool
   

3. Namespace Conflicts: Avoid naming custom packs lang.php—use unique names like custom.php.

Debugging

• Log Missing Keys: Enable debug mode in config/lang.php:

  'debug' => env('APP_DEBUG', false),
  

  Missing keys will log to storage/logs/laravel.log.

• Check Loaded Packs:

  dd(Lang::getLoadedPacks()); // Array of loaded locales
  

Extension Points

1. Custom Pack Sources: Extend LaravelLang\Common\Contracts\PackLoader to load from custom paths (e.g., S3):

   Lang::extend('s3', function ($locale) {
       return new CustomS3Loader($locale);
   });
   

2. Override Default Behavior: Bind your own Lang facade to replace the default implementation:

   Facade::bind('Lang', CustomLangFacade::class);
   

3. Event Listeners: Listen for lang.pack.loaded events to run post-load logic:

   Lang::load('en', [], function () {
       // Post-load logic (e.g., cache translations)
   });
   

Pro Tips

• Performance: Pre-load packs during boot for static sites:

  public function boot()
  {
      if (app()->environment('production')) {
          Lang::load('en', 'es'); // Load all needed packs upfront
      }
  }
  

• JSON Packs: Use .json files for dynamic packs (e.g., user-generated content):

  Lang::load('dynamic', [], 'json');