Dotenv Updater Bundle Laravel Package

Getting Started

Minimal Setup for Laravel Developers

1. Install the Package:

   composer require atournayre/dotenv-updater-bundle
   

   Note: While this is a Symfony bundle, it works seamlessly in Laravel due to Symfony’s compatibility with Laravel’s service container.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Atournayre\DotEnvUpdaterBundle\AtournayreDotEnvUpdaterBundle::class => ['all' => true],
       // ...
   ];
   

3. First Use Case: Update .env.local.php from .env (common for local overrides):

   php artisan dotenv:update
   

   Why? This automates syncing your base .env with local overrides, reducing manual edits.

Implementation Patterns

Daily Workflow Integration

1. CI/CD Pipeline Updates: Trigger updates post-deploy to sync environment-specific .env files (e.g., .env.prod.php):

   php artisan dotenv:update .env.prod.php
   

   Use Case: Automate environment-specific configurations (e.g., database URLs, API keys) without hardcoding secrets in Git.

2. Dynamic Configuration: Update specific variables (e.g., feature flags) without redeploying:

   php artisan dotenv:update:element .env.prod.php APP_DEBUG=false
   

   Use Case: Toggle features or adjust settings dynamically (e.g., during A/B testing).

3. Debugging: Inspect .env files before updating:

   php artisan dotenv:update --debug
   

   Use Case: Verify values before applying changes in staging/production.

Advanced Patterns

1. Pre-Update Validation: Extend the bundle to validate values before updating (e.g., regex for email formats):

   // In a custom service or event listener
   $validator = Validator::make(['value' => $newValue], ['value' => 'email']);
   if ($validator->fails()) {
       throw new \RuntimeException('Invalid email format');
   }
   

2. Event-Driven Updates: Hook into Laravel events (e.g., ConfigCached) to auto-update .env files:

   // In EventServiceProvider
   protected $listen = [
       'config.cached' => [\App\Listeners\UpdateEnvFiles::class],
   ];
   

3. Secret Manager Integration: Fetch values from AWS Secrets Manager/Vault and update .env:

   # Pseudocode in a custom command
   $secret = $awsSecretsManager->getSecret('db_credentials');
   php artisan dotenv:update:element .env.prod.php DB_PASSWORD=$secret['password']
   

Gotchas and Tips

Common Pitfalls

1. File Permissions:

   • Issue: php artisan dotenv:update fails with "Permission denied".
   • Fix: Ensure the .env file and its directory are writable by the Laravel user:

     chmod 644 .env.prod.php
     chmod 755 .env.d/
     

2. Missing .env Files:

   • Issue: The bundle only updates existing .env.*.php files (won’t create them).
   • Fix: Pre-generate files with touch .env.local.php or use a template.

3. Cache Invalidation:

   • Issue: Updated .env values aren’t reflected in the app.
   • Fix: Clear Laravel’s cache after updates:

     php artisan config:clear
     php artisan cache:clear
     

4. Concurrent Updates:

   • Issue: Race conditions if multiple processes update .env simultaneously.
   • Fix: Use the --lock flag (if supported) or implement file locking in a custom command.

Debugging Tips

1. Dry Run: Use --debug to preview changes without applying them:

   php artisan dotenv:update --debug
   

2. Log Updates: Enable Symfony’s profiler or add logging to track changes:

   // config/services.php
   'monolog' => [
       'handlers' => [
           'dotenv_updater' => [
               'type' => 'stream',
               'path' => storage_path('logs/dotenv-updater.log'),
           ],
       ],
   ];
   

3. Custom Validation: Override the bundle’s update logic to add rules:

   // src/Command/DotenvUpdateCommand.php (extend the original)
   protected function updateValue(string $file, string $key, string $value): void
   {
       if (!preg_match('/^[a-zA-Z0-9_]+$/', $key)) {
           throw new \InvalidArgumentException("Invalid key format: $key");
       }
       // Proceed with update
   }
   

Extension Points

1. Custom Commands: Extend the bundle’s commands for team-specific needs:

   php artisan make:command CustomDotenvUpdate
   

   Example: Add Slack notifications for .env changes.

2. Environment-Specific Logic: Use Laravel’s app()->environment() to conditionally update files:

   if (app()->environment('production')) {
       $this->updateEnvFile('.env.prod.php');
   }
   

3. Audit Logging: Track who/when updated .env files by integrating with Laravel’s auth system:

   // In a custom listener
   \App\Models\EnvUpdateLog::create([
       'user_id' => auth()->id(),
       'file' => $file,
       'changes' => json_encode($changes),
   ]);
   

Configuration Quirks

1. Bundle Disabled by Default: Ensure the bundle is enabled in bundles.php (Symfony’s requirement).

2. Symfony Dependency: If using Laravel <8.0, ensure Symfony components (e.g., symfony/console) are compatible.

3. Case Sensitivity: .env keys are case-sensitive. Ensure consistency when updating:

   # Correct:
   php artisan dotenv:update:element .env.local.php APP_DEBUG=false
   # Incorrect (will fail silently):
   php artisan dotenv:update:element .env.local.php app_debug=false