Config Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-lang/config
   

   Publish the config file:

   php artisan vendor:publish --provider="LaravelLang\Config\LaravelLangConfigServiceProvider" --tag="config"
   

   This generates config/lang.php in your project.

2. First Use Case: Configure default locale and fallback locales in config/lang.php:

   return [
       'default_locale' => 'en',
       'fallback_locale' => 'en',
       'supported_locales' => ['en', 'es', 'fr'],
       'paths' => [
           resource_path('lang'),
       ],
   ];
   

   Now, Laravel-Lang packages (e.g., laravel-lang/lang) will automatically use these settings.

Where to Look First

• Config File: config/lang.php – Centralized configuration for all Laravel-Lang packages.
• Service Provider: LaravelLang\Config\LaravelLangConfigServiceProvider – Registers and bootstraps the package.
• Facade: LaravelLangConfig – Access helper methods (e.g., LaravelLangConfig::initialize()).
• Documentation: Check the Laravel-Lang Config README for advanced usage.

Implementation Patterns

Usage Patterns

1. Centralized Configuration: Use config/lang.php to define:

   • Default and fallback locales.
   • Supported locales (e.g., ['en', 'es', 'fr']).
   • Paths to translation files (supports arrays for multiple paths).
   • Loader settings (e.g., loader => 'json').

   Example:

   return [
       'default_locale' => env('APP_LOCALE', 'en'),
       'fallback_locale' => 'en',
       'supported_locales' => ['en', 'es', 'fr', 'de_AT'],
       'paths' => [
           resource_path('lang'),
           base_path('custom/translations'),
       ],
       'loader' => 'json', // or 'php', 'yaml'
   ];
   

2. Environment-Specific Overrides: Override settings per environment using .env or conditional logic in config/lang.php:

   'default_locale' => env('APP_LOCALE', config('app.locale')),
   

3. Integration with Laravel-Lang Packages: The package works seamlessly with other Laravel-Lang tools like:

   • laravel-lang/lang: Uses config/lang.php for locale paths and loaders.
   • laravel-lang/routes: Configure route localization metadata (e.g., meta, directory).
   • laravel-lang/publisher: Publishes translation files using settings from config/lang.php.

   Example for routes:

   'routes' => [
       'meta' => [
           'prefix' => 'api',
           'middleware' => ['api'],
       ],
       'directory' => 'api',
   ],
   

4. Dynamic Initialization: Use the LaravelLangConfig facade to initialize or reset configurations dynamically:

   use LaravelLang\Config\Facades\LaravelLangConfig;
   
   LaravelLangConfig::initialize(); // Re-initialize with current config
   

5. Publishing Custom Configs: Extend or override the default config by publishing additional files:

   php artisan vendor:publish --provider="LaravelLang\Config\LaravelLangConfigServiceProvider" --tag="config"
   

   Then modify the published config/lang.php to suit your needs.

Workflows

1. New Project Setup:

   • Install the package.
   • Publish the config file.
   • Define locales, paths, and loaders in config/lang.php.
   • Install other Laravel-Lang packages (e.g., laravel-lang/lang) to automatically inherit settings.

2. Multi-Language Project:

   • Add supported locales to config/lang.php.
   • Place translation files in the defined paths (e.g., resources/lang/es/).
   • Use the App facade or middleware to set the locale dynamically:

     use Illuminate\Support\Facades\App;
     
     App::setLocale('es');
     

3. Route Localization:

   • Configure route-specific settings in config/lang.php under the routes key.
   • Use the LaravelLang\Routes package to generate localized routes:

     Route::lang('es')->get('/saludo', function () {
         return 'Hola';
     });
     

4. CI/CD Pipeline:

   • Store config/lang.php in version control.
   • Use environment variables (e.g., APP_LOCALE) to override settings per environment.
   • Ensure consistency across dev/staging/production by validating the config in your pipeline.

Integration Tips

1. Combine with Laravel-Lang/Lang: The package works out-of-the-box with laravel-lang/lang. Ensure your translation files are in the correct paths (e.g., resources/lang/{locale}/).

2. Custom Loaders: If you need a custom loader (e.g., for .po files), extend the package or use Laravel’s built-in loader system alongside this package.

3. Middleware for Locale Switching: Create middleware to switch locales based on user preferences or headers:

   namespace App\Http\Middleware;
   
   use Closure;
   use Illuminate\Support\Facades\App;
   
   class SetLocale
   {
       public function handle($request, Closure $next)
       {
           if ($locale = $request->header('Accept-Language')) {
               App::setLocale($locale);
           }
           return $next($request);
       }
   }
   

4. Testing: Override the config in tests using config() or Mockery:

   $this->app->singleton('config', function ($app) {
       return new \Illuminate\Config\Repository([
           'lang' => [
               'default_locale' => 'test',
               'fallback_locale' => 'en',
           ],
       ]);
   });
   

5. Localization in Blade: Use the @lang directive or trans() helper:

   <h1>@lang('welcome.title')</h1>
   

   Or:

   echo trans('welcome.title');
   

Gotchas and Tips

Pitfalls

1. Unsupported Laravel Versions:

   • The package drops support for Laravel 10 in v2.x. Ensure compatibility with your Laravel version.
   • Check the releases for supported versions.

2. Config File Overrides:

   • If you publish the config file and later update the package, your customizations may be overwritten. Use --force or manually merge changes:

     php artisan vendor:publish --provider="LaravelLang\Config\LaravelLangConfigServiceProvider" --tag="config" --force
     

3. Locale Paths:

   • Ensure the paths array in config/lang.php points to valid directories. Invalid paths will cause errors when loading translations.
   • Example of valid paths:

     'paths' => [
         resource_path('lang'),
         base_path('custom/translations'),
     ],
     

4. Fallback Locale Logic:

   • The fallback_locale setting must be one of the supported_locales. Otherwise, fallback logic may fail silently or throw errors.
   • Example:

     'fallback_locale' => 'en', // Must be in 'supported_locales'
     'supported_locales' => ['en', 'es', 'fr'],
     

5. Loader Conflicts:

   • If you mix loaders (e.g., json and php), ensure translation files are consistent in format. Mismatches may cause parsing errors.
   • Example of loader settings:

     'loader' => 'json', // or 'php', 'yaml'
     

6. Route Configuration:

   • The meta and directory keys for routes were renamed from map in v2.2.0. Update your config if you’re upgrading:

     // Old (v1.x)
     'map' => [...]
     
     // New (v2.x)
     'meta' => [...]
     

7. IDE Helper Files:

   • The package generates IDE helper files (e.g., for PhpStorm) in vendor/laravel-lang/config/helpers. If these cause issues, disable them by setting VENDOR_PATH in your .env:

     VENDOR_PATH=
     

Debugging

1. Missing Translation Files:

   • Check that translation files exist in the paths defined in config/lang.php.
   • Verify file permissions (e.g., chmod -R 755 resources/lang).

2. Locale Not Switching:

   • Ensure the locale is being set correctly (e.g., via middleware or App::setLocale()).
   • Check for typos in locale codes (e.g., es vs. ES).