Dotenv Editor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require jackiedo/dotenv-editor
   

   Publish the config file (optional):

   php artisan vendor:publish --provider="JackieDo\DotenvEditor\DotenvEditorServiceProvider" --tag="config"
   

2. First Use Case: Access the editor via the provided route (default: /dotenv-editor):

   php artisan route:list | grep dotenv-editor
   

   Navigate to the URL in your browser to edit .env variables interactively.

3. Key Files:

   • config/dotenv-editor.php (for customization)
   • routes/web.php (ensure the route is included if not auto-discovered)

Implementation Patterns

Workflow Integration

1. Environment-Specific Edits: Use the DotenvEditor facade to programmatically modify .env files:

   use JackieDo\DotenvEditor\Facades\DotenvEditor;
   
   DotenvEditor::set('APP_ENV', 'local');
   DotenvEditor::save();
   

2. Validation Hooks: Extend validation logic by binding to the dotenv-editor.saving event:

   DotenvEditor::extend(function ($editor) {
       $editor->validate(function ($key, $value) {
           if ($key === 'DB_PASSWORD' && strlen($value) < 8) {
               throw new \InvalidArgumentException('Password must be at least 8 characters.');
           }
       });
   });
   

3. Multi-Environment Management: Use the DotenvEditor::load() method to switch between .env files dynamically:

   DotenvEditor::load('.env.staging');
   

4. API Access: Expose the editor via an API endpoint for headless applications:

   Route::post('/api/env', function (Request $request) {
       DotenvEditor::set($request->key, $request->value);
       DotenvEditor::save();
       return response()->json(['success' => true]);
   });
   

5. Seeding Defaults: Populate .env with defaults during deployment:

   DotenvEditor::setDefault('APP_DEBUG', env('APP_ENV') !== 'production');
   

Gotchas and Tips

Pitfalls

1. File Permissions: Ensure the .env file is writable by the web server user:

   chmod 644 .env
   

   Debugging: Check Laravel logs for Permission denied errors.

2. Caching Issues: Clear config cache after manual .env edits:

   php artisan config:clear
   

3. Hidden Characters: Avoid copying .env values from rich-text editors (e.g., Word, Slack). Use plain text editors or pbcopy/pbpaste.

4. Route Conflicts: The default route (/dotenv-editor) may conflict with other packages. Rename it in config/dotenv-editor.php:

   'route' => [
       'path' => 'admin/env',
       'middleware' => ['web', 'auth'],
   ],
   

5. Sensitive Data Exposure: Never commit .env to version control. Use .env.example as a template and .gitignore to exclude .env.

Debugging Tips

1. Log Changes: Enable debug mode in config/dotenv-editor.php:

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

   Logs will appear in storage/logs/laravel.log.

2. Validate Syntax: Use DotenvEditor::validate() to check for malformed key-value pairs:

   try {
       DotenvEditor::validate();
   } catch (\InvalidArgumentException $e) {
       report($e);
   }
   

3. Backup .env: Create a backup before bulk edits:

   cp .env .env.bak-$(date +%Y%m%d)
   

Extension Points

1. Custom Storage: Override the default .env path by binding a custom DotenvEditor implementation:

   $this->app->bind('jackiedo/dotenv-editor', function () {
       return new \JackieDo\DotenvEditor\CustomDotenvEditor('/path/to/custom.env');
   });
   

2. GUI Themes: Extend the Blade view (resources/views/vendor/dotenv-editor/index.blade.php) to customize the UI (e.g., dark mode, monospace fonts).

3. Encryption: Integrate with Laravel's encryption services to secure sensitive values:

   DotenvEditor::extend(function ($editor) {
       $editor->encrypting = true;
   });
   

4. Webhook Triggers: Dispatch events on save to trigger external actions (e.g., restart services):

   DotenvEditor::extend(function ($editor) {
       $editor->onSave(function () {
           \Artisan::call('queue:restart');
       });
   });