README

A powerful Laravel package for merging multiple .env files with patch support and advanced features.

Envsemble allows you to maintain a base environment configuration and apply targeted patches for different environments, features, or deployment scenarios. Perfect for managing complex Laravel applications with multiple deployment targets.

✨ Features

🔧 Base + Patch Architecture: Start with a base .env file and apply patches
🗑️ Key Deletion: Use KEY=__DELETE__ to remove keys during merge
📝 Source Tracking: Each line in the output shows which file it came from
🔍 Dry Run Mode: Preview changes before applying them
📊 Detailed Reports: See what was added, modified, or deleted
🗜️ Squash Mode: Combine all files into a new base and remove patches
🎯 CLI Integration: Full Laravel Artisan command support
✅ Comprehensive Tests: Full PHPUnit/Pest test coverage

📦 Installation

Install via Composer:

composer require joe1992w/envsemble

For Laravel applications, the service provider will be auto-discovered. For manual registration:

// config/app.php
'providers' => [
    // ...
    JoeWare\Envsemble\EnvsembleServiceProvider::class,
],

🚀 Quick Start

1. Basic Usage

php artisan env:build --base=.env.base --patches=env-patches/ --out=.env.generated

2. Dry Run (Preview Changes)

php artisan env:build --base=.env.base --patches=env-patches/ --out=.env.generated --dry-run

3. Squash Mode (Combine All Files)

php artisan env:build --base=.env.base --patches=env-patches/ --out=.env.new --squash

📁 File Structure Example

project/
├── .env.base                 # Base environment file
├── env-patches/              # Directory containing patch files
│   ├── 01-development.env    # Development overrides
│   ├── 02-local-testing.env  # Testing configuration
│   └── 03-mail-debug.env     # Mail debugging settings
└── .env.generated            # Final merged output

📝 Syntax Examples

Base File (.env.base)

APP_NAME="My Laravel App"
APP_ENV=production
APP_DEBUG=false
DB_HOST=127.0.0.1
DB_DATABASE=production_db
CACHE_DRIVER=redis
MAIL_MAILER=smtp

Patch File (01-development.env)

# Override for development
APP_ENV=local
APP_DEBUG=true

# Add new keys
LOG_LEVEL=debug
TELESCOPE_ENABLED=true

# Delete keys (removes from final output)
CACHE_DRIVER=__DELETE__

Generated Output (.env.generated)

# Generated by Envsemble on 2025-06-03 10:30:00
# Base: .env.base
# Patches: 01-development.env

APP_NAME="My Laravel App" # from: .env.base
APP_ENV=local # from: 01-development.env
APP_DEBUG=true # from: 01-development.env
DB_HOST=127.0.0.1 # from: .env.base
DB_DATABASE=production_db # from: .env.base
MAIL_MAILER=smtp # from: .env.base
LOG_LEVEL=debug # from: 01-development.env
TELESCOPE_ENABLED=true # from: 01-development.env

🛠️ Command Options

Option	Description	Required
`--base`	Path to the base .env file	✅
`--patches`	Directory containing patch files	✅
`--out`	Output file path	✅
`--dry-run`	Preview changes without writing files	❌
`--no-comments`	Exclude source comments from output	❌
`--squash`	Combine all files and remove patches	❌

📊 Merge Reports

After each merge, Envsemble provides a detailed report:

📊 Merge Report:
┌─────────────────────┬───────┐
│ Metric              │ Count │
├─────────────────────┼───────┤
│ Base file keys      │ 15    │
│ Patch files processed│ 3     │
│ Keys added          │ 4     │
│ Keys modified       │ 3     │
│ Keys deleted        │ 2     │
│ Final output keys   │ 20    │
└─────────────────────┴───────┘

➕ Added keys: LOG_LEVEL, TELESCOPE_ENABLED, DEBUGBAR_ENABLED, API_KEY
🔄 Modified keys: APP_ENV, APP_DEBUG, MAIL_MAILER
🗑️  Deleted keys: REDIS_HOST, CACHE_DRIVER

📁 Files processed:
   Base: .env.base
   Patch: 01-development.env
   Patch: 02-testing.env
   Patch: 03-debug.env

📈 Efficiency: 133.3% keys retained/added from base

🔧 Programmatic Usage

You can also use Envsemble programmatically:

use JoeWare\Envsemble\EnvMerger;

$merger = new EnvMerger();

// Basic merge
$result = $merger->merge('.env.base', 'env-patches/');
$output = $merger->generateOutput($result);
file_put_contents('.env.generated', $output);

// Get detailed report
$report = $result->getReport();
echo "Added {$result->getAddedKeysCount()} keys\n";
echo "Modified {$result->getModifiedKeysCount()} keys\n";

// Squash files
$result = $merger->squash('.env.base', 'env-patches/', '.env.new');

🏗️ Advanced Use Cases

Environment-Specific Builds

# Development
php artisan env:build --base=.env.base --patches=patches/dev/ --out=.env

# Staging  
php artisan env:build --base=.env.base --patches=patches/staging/ --out=.env

# Production
php artisan env:build --base=.env.base --patches=patches/prod/ --out=.env

Feature Flag Management

# Enable feature flags
php artisan env:build --base=.env.base --patches=features/feature-x/ --out=.env

# Disable feature (using __DELETE__ in patch)
php artisan env:build --base=.env.base --patches=features/disable-feature-x/ --out=.env

CI/CD Integration

# GitHub Actions example
- name: Build Environment
  run: |
    php artisan env:build \
      --base=.env.production \
      --patches=deploy/patches/ \
      --out=.env \
      --no-comments

🧪 Testing

Run the test suite:

composer test

Individual test commands:

composer test:unit      # Unit tests
composer test:types     # Static analysis
composer test:lint      # Code style

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This package is open-sourced software licensed under the MIT license.

🙋‍♂️ Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ by Joe Ware

joe1992w / envsemble

Maintainers

Details