Envy Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require worksome/envy --dev
   

   Publish the config file:

   php artisan vendor:publish --provider="Worksome\Envy\EnvyServiceProvider" --tag="config"
   

2. First Use Case Run the sync command to generate/update .env and .env.example files:

   php artisan envy:sync
   

   • Review the generated files in your project root.
   • Commit the updated .env.example to version control (never commit .env itself).

3. Where to Look First

   • Config File: config/envy.php – Customize sync behavior (e.g., excluded keys, file paths).
   • Artisan Commands: php artisan envy:sync (sync), php artisan envy:diff (compare changes).
   • Documentation: Focus on the README for CLI flags and examples.

Implementation Patterns

Core Workflows

1. Onboarding New Developers

   • Run php artisan envy:sync in the project root to auto-generate .env.example with all config keys from config/ files.
   • Share .env.example via version control; developers run cp .env.example .env and populate values locally.
   • Pro Tip: Add a post-clone hook in your repo (e.g., GitHub Actions) to auto-run envy:sync on fresh clones.

2. Adding New Configuration

   • Add a new key to config/services.php (or any config file).
   • Run php artisan envy:sync to update .env.example with the new key (default value: null).
   • Document the new env var in your team’s onboarding docs.

3. Environment-Specific Syncs

   • Use --env flag to sync only specific environments (e.g., php artisan envy:sync --env=staging).
   • Leverage config/envy.php to define environment-specific templates (e.g., staging.env.example).

4. CI/CD Integration

   • Run envy:sync in your CI pipeline (e.g., GitHub Actions) to validate .env.example is up-to-date before merging:

     - name: Sync env files
       run: php artisan envy:sync --validate
     

   • Use --dry-run to preview changes without modifying files.

Integration Tips

• Laravel Forge/Vapor: Sync .env.example during deploy prep to ensure consistency across servers.
• Shared Hosting: Exclude sensitive keys (e.g., APP_KEY) from .env.example using config/envy.php:

  'exclude' => [
      'APP_KEY',
      'DB_PASSWORD',
  ],
  

• Monorepos: Use --path to sync env files for specific sub-projects:

  php artisan envy:sync --path=packages/api
  

Gotchas and Tips

Pitfalls

1. Sensitive Data Leaks

   • Risk: Accidentally committing .env or exposing secrets in .env.example.
   • Fix: Always exclude sensitive keys (e.g., APP_KEY, DB_PASSWORD) in config/envy.php:

     'exclude' => ['APP_*', 'DB_*', 'AWS_*'],
     

   • Double-Check: Run php artisan envy:diff before committing .env.example to spot unintended exposures.

2. Overwriting Local .env

   • Risk: envy:sync may overwrite existing .env if not careful.
   • Fix: Use --dry-run first or exclude .env from sync:

     'files' => [
         '.env.example' => '.env.example',
         // '.env' => '.env', // Commented out to avoid overwriting
     ],
     

3. Config File Changes Not Reflected

   • Cause: Cached config or stale .env.example.
   • Fix: Clear config cache (php artisan config:clear) and run envy:sync again.

4. Custom Config Parsing Issues

   • Cause: Envy may not detect nested config arrays (e.g., config/services.php with complex structures).
   • Fix: Use the custom option in config/envy.php to manually define keys:

     'custom' => [
         'SERVICE_X' => 'services.x.api_key',
     ],
     

Debugging

• Verbose Output: Use -v flag for detailed logs:

  php artisan envy:sync -v
  

• Validate Config: Run php artisan envy:validate to check if .env.example matches your config.
• Check for Errors: If sync fails, inspect storage/logs/laravel.log for parsing issues.

Extension Points

1. Custom Templates Override default templates by publishing assets:

   php artisan vendor:publish --tag="envy-views"
   

   Modify resources/views/vendor/envy/ to change file headers or formats.

2. Pre/Post-Sync Hooks Add logic before/after sync via service provider:

   Envy::extend(function ($envy) {
       $envy->beforeSync(function () {
           // Pre-sync logic (e.g., backup .env)
       });
   });
   

3. Dynamic Key Generation Use config/envy.php to dynamically generate keys from config:

   'custom' => [
       'QUEUE_CONNECTIONS' => function () {
           return collect(config('queue.connections'))->keys()->implode(',');
       },
   ],
   

4. Git Hooks Automate syncs with a pre-commit hook to ensure .env.example is never outdated:

   # .git/hooks/pre-commit
   php artisan envy:validate || exit 1