Skip to content

🔏 Laravel Configrypt lets you encrypt secrets directly in your .env file using a secure key, and automatically decrypts them when accessed via Laravel’s env() or configuration helpers.

License

Notifications You must be signed in to change notification settings

Grazulex/laravel-configrypt

Laravel Configrypt

Laravel Configrypt

Encrypt sensitive values in your Laravel .env file and decrypt them using helper functions that work around Laravel's environment caching limitations.

Latest Version Total Downloads License PHP Version Laravel Version Tests Code Style

🔐 Overview

🔏 Laravel Configrypt lets you encrypt secrets directly in your .env file using a secure key, and decrypt them using reliable helper functions that work around Laravel's environment caching limitations.

It protects values like API tokens, database credentials, or secret keys — especially when sharing .env files across environments or storing encrypted configs in source control or CI/CD.

✨ Features

  • 🔐 Encrypt .env values using AES-256
  • 🔓 Reliable decryption with helper functions
  • 🔧 Seamless Laravel integration via service provider
  • 🔑 Custom encryption key support (fallback to APP_KEY)
  • 🛡️ Secure by default: decryption only happens inside app runtime
  • ⚙️ Configurable via config/configrypt.php
  • 🧪 Safe for CI/CD, secrets rotation, and external vault injection

💡 Example

In your .env:

MAIL_PASSWORD=ENC:gk9AvRZgx6Jyds7K2uFctw==

In your Laravel code:

// Method 1: Use helper functions (recommended)
$password = configrypt_env('MAIL_PASSWORD');     // returns decrypted value
$password = encrypted_env('MAIL_PASSWORD');      // alias for configrypt_env()

// Method 2: Use the Str macro for easy migration
use Illuminate\Support\Str;
$password = Str::decryptEnv('MAIL_PASSWORD');    // easy search & replace from env()

// Method 3: Use the environment facade
use LaravelConfigrypt\Facades\ConfigryptEnv;
$password = ConfigryptEnv::get('MAIL_PASSWORD'); // returns decrypted value

// Method 4: Manual decryption
use LaravelConfigrypt\Facades\Configrypt;
$rawValue = env('MAIL_PASSWORD'); // still encrypted due to Laravel's env cache
$password = Configrypt::decrypt($rawValue);      // manual decrypt

// Note: env('MAIL_PASSWORD') returns encrypted value due to Laravel's cache limitation

⚙️ Configuration

Publish the config:

php artisan vendor:publish --tag=configrypt-config

Result in config/configrypt.php:

return [
    // Use a dedicated key or fallback to APP_KEY
    'key' => env('CONFIGRYPT_KEY', env('APP_KEY')),

    // Prefix used to identify encrypted values
    'prefix' => env('CONFIGRYPT_PREFIX', 'ENC:'),

    // Cipher method
    'cipher' => env('CONFIGRYPT_CIPHER', 'AES-256-CBC'),

    // Auto decrypt (deprecated - has no effect)
    'auto_decrypt' => env('CONFIGRYPT_AUTO_DECRYPT', false),
];

🚀 Quick Start

1. Install the package

composer require grazulex/laravel-configrypt

2. Publish configuration (optional)

php artisan vendor:publish --tag=configrypt-config

3. Encrypt your secrets

php artisan configrypt:encrypt "my-super-secret-password"

Output:

Encrypted value:
ENC:gk9AvRZgx6Jyds7K2uFctw==

You can now use this encrypted value in your .env file:
SOME_SECRET=ENC:gk9AvRZgx6Jyds7K2uFctw==

4. Add to your .env file

DB_PASSWORD=ENC:gk9AvRZgx6Jyds7K2uFctw==
API_SECRET=ENC:XyZ123AbC456DeF789GhI012JkL==
JWT_SECRET=ENC:MnOpQrStUvWxYzAbCdEfGhIjKl==

5. Use in your application

⚠️ Important: Laravel's env() function cannot be automatically decrypted due to early caching.

// ❌ This won't work - Laravel caches env() before our package loads
$dbPassword = env('DB_PASSWORD'); // Returns "ENC:xyz..." (still encrypted)

// ✅ Use our helper functions instead (recommended)
$dbPassword = configrypt_env('DB_PASSWORD');  // Returns decrypted value
$apiSecret = encrypted_env('API_SECRET');     // Alias for consistency

// ✅ Or use the facade for more control
use LaravelConfigrypt\Facades\ConfigryptEnv;
$dbPassword = ConfigryptEnv::get('DB_PASSWORD');

// ✅ Or use the Str macro for easy migration
use Illuminate\Support\Str;
$dbPassword = Str::decryptEnv('DB_PASSWORD');

⚠️ Important: Laravel env() Cache Limitation

Laravel caches environment variables very early in the boot process, before service providers load. This means the standard env() function cannot be automatically decrypted.

🔧 Solution: Use Helper Functions

// ❌ This won't work - returns encrypted value
$password = env('DB_PASSWORD'); // Still returns "ENC:xyz..."

// ✅ These work - return decrypted values
$password = configrypt_env('DB_PASSWORD');
$password = encrypted_env('DB_PASSWORD');
$password = ConfigryptEnv::get('DB_PASSWORD');

🚀 Quick Migration

Find and replace in your codebase:

# Replace env() calls with configrypt_env()
find . -name "*.php" -exec sed -i 's/env(/configrypt_env(/g' {} \;

# Or use Str::decryptEnv() for easier reversal
find . -name "*.php" -exec sed -i 's/env(/Str::decryptEnv(/g' {} \;

🔧 Advanced Usage

Using the Facades

use LaravelConfigrypt\Facades\Configrypt;
use LaravelConfigrypt\Facades\ConfigryptEnv;

// Encrypt a value
$encrypted = Configrypt::encrypt('my-secret-value');

// Decrypt a value
$decrypted = Configrypt::decrypt('ENC:encrypted-value');

// Check if a value is encrypted
$isEncrypted = Configrypt::isEncrypted('ENC:some-value');

// Environment-specific methods
$dbPassword = ConfigryptEnv::get('DB_PASSWORD');
$allDecrypted = ConfigryptEnv::getAllDecrypted();

Helper Functions

// Primary helper functions (recommended approach)
$dbPassword = configrypt_env('DB_PASSWORD', 'default-value');
$apiKey = encrypted_env('API_KEY'); // alias for configrypt_env()

// Str macro for easy migration from env() calls
use Illuminate\Support\Str;
$secret = Str::decryptEnv('JWT_SECRET');

Dependency Injection

use LaravelConfigrypt\Services\ConfigryptService;
use LaravelConfigrypt\Services\EnvironmentDecryptor;

class MyController extends Controller
{
    public function __construct(
        private ConfigryptService $configrypt,
        private EnvironmentDecryptor $envDecryptor
    ) {
    }

    public function encryptValue(Request $request)
    {
        $encrypted = $this->configrypt->encrypt($request->value);
        return response()->json(['encrypted' => $encrypted]);
    }

    public function getDecryptedEnv(string $key)
    {
        return $this->envDecryptor->get($key);
    }
}

🧪 Practical Examples

Database Configuration

# Encrypt your database password
DB_PASSWORD=ENC:W3+f/2ZzZfl9KQ==
// config/database.php
'mysql' => [
    'driver' => 'mysql',
    'password' => configrypt_env('DB_PASSWORD'), // Use helper function
],

API Keys Management

# Third-party service credentials
STRIPE_SECRET=ENC:Nq8j8hlc3PMp9uE=
MAILGUN_SECRET=ENC:XYZ123456789abc=
AWS_SECRET_ACCESS_KEY=ENC:AbCdEf1234567890=
// config/services.php
'stripe' => [
    'secret' => configrypt_env('STRIPE_SECRET'),
],

'mailgun' => [
    'secret' => configrypt_env('MAILGUN_SECRET'),
],

// config/filesystems.php
's3' => [
    'driver' => 's3',
    'secret' => configrypt_env('AWS_SECRET_ACCESS_KEY'),
],

Multi-Environment Setup

# Development
CONFIGRYPT_KEY=dev-key-32-characters-long-----
DB_PASSWORD=ENC:dev-encrypted-password

# Production  
CONFIGRYPT_KEY=prod-key-32-characters-long----
DB_PASSWORD=ENC:prod-encrypted-password

More examples are available in the Examples Wiki.

🔑 Changing Keys

You can define a custom CONFIGRYPT_KEY in .env to use a dedicated encryption key different from APP_KEY.

💡 Remember: only encrypted values with the correct key can be decrypted. Keep your key safe!

🛡️ Security Considerations

  • Environment Variable Safety: Decrypted values never touch disk after load, only stored in runtime memory
  • Prefix Protection: ENC: prefix ensures only intended values are decrypted
  • Error Handling: Graceful fallbacks prevent application crashes from decryption failures
  • Key Management: Only encrypted values with the correct key can be decrypted - keep your key safe!
  • Production Usage: Ideal for .env.staging, .env.production, or vault-managed .env overrides
  • Team Sharing: Perfect for sharing .env securely in teams or across pipelines

📚 Documentation

Comprehensive documentation and examples are available in the GitHub Wiki:

📄 License

MIT License — see LICENSE.md


Made with 🔐 for Laravel developers who care about secrets.

About

🔏 Laravel Configrypt lets you encrypt secrets directly in your .env file using a secure key, and automatically decrypts them when accessed via Laravel’s env() or configuration helpers.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Sponsor this project

  •  

Contributors 2

  •  
  •  

Languages