README

Part of Jardis — the Domain-Driven Design platform for PHP. You model your domain; Jardis generates the production-ready hexagonal code (DTOs, Command/Query handlers, repositories, persistence). This package is part of the open-source foundation that generated code runs on.

Encrypted .env secrets for PHP — encrypt configuration values with AES-256-GCM or Sodium, store them safely in .env files, and decrypt transparently at load time. Plugs into the DotEnv cast chain — no manual decryption calls needed.

Features

• AES-256-GCM Encryption — authenticated encryption via OpenSSL; AesSecretResolver handles encrypt and decrypt
• Sodium XSalsa20-Poly1305 — libsodium-based encryption via SodiumSecretResolver with explicit sodium: prefix
• DotEnv Integration — SecretHandler plugs directly into DotEnv::addHandler() as a prepended cast handler
• Resolver Chain — SecretResolverChain delegates to the first resolver whose prefix matches the encrypted value
• Key Providers — FileKeyProvider reads a 32-byte key from a file; EnvKeyProvider reads from an environment variable; both auto-detect base64 encoding
• Makefile Tooling — make generate-key-file, make encrypt, and make encrypt-sodium for setup and secret rotation
• Typed Exceptions — InvalidKeyException and DecryptionFailedException for precise error handling

Installation

composer require jardissupport/secret

Quick Start

1. Generate a key and encrypt a value

make generate-key-file                      # Creates support/secret.key
make encrypt VALUE="my-database-password"   # Outputs: secret(base64...)

2. Store the encrypted value in .env

DB_PASSWORD=secret(base64encodedEncryptedValue)

3. Integrate with DotEnv

use JardisSupport\DotEnv\DotEnv;
use JardisSupport\Secret\Handler\SecretHandler;
use JardisSupport\Secret\KeyProvider\FileKeyProvider;

$dotEnv = new DotEnv();
$dotEnv->addHandler(
    new SecretHandler(new FileKeyProvider('support/secret.key')),
    prepend: true,
);

$config = $dotEnv->loadPrivate('/path/to/app');
// $config['DB_PASSWORD'] → decrypted plaintext, no secret() wrapper

Advanced Usage

use JardisSupport\Secret\Handler\SecretHandler;
use JardisSupport\Secret\Handler\SecretResolverChain;
use JardisSupport\Secret\KeyProvider\EnvKeyProvider;
use JardisSupport\Secret\KeyProvider\FileKeyProvider;
use JardisSupport\Secret\Resolver\AesSecretResolver;
use JardisSupport\Secret\Resolver\SodiumSecretResolver;
use JardisSupport\DotEnv\DotEnv;

// Key from environment variable instead of a file
// EnvKeyProvider auto-detects base64-encoded keys
$keyProvider = new EnvKeyProvider('APP_SECRET_KEY');

// Build a custom resolver chain with explicit ordering
// Sodium resolver matches 'sodium:...' prefix; AES is the catch-all fallback
$chain = (new SecretResolverChain())
    ->addResolver(new SodiumSecretResolver($keyProvider))
    ->addResolver(new AesSecretResolver($keyProvider));

// Encrypt a Sodium value (e.g. in a setup script)
// make encrypt-sodium VALUE="my-api-key"  → secret(sodium:base64...)

// .env with mixed encryption algorithms:
//   DB_PASSWORD=secret(base64AesEncryptedValue)
//   API_KEY=secret(sodium:base64SodiumEncryptedValue)
//   PLAIN=no-encryption-needed

$dotEnv = new DotEnv();
$dotEnv->addHandler(new SecretHandler($keyProvider), prepend: true);

// SecretHandler automatically wires both AES and Sodium resolvers;
// use a manual chain only when you need fine-grained resolver control
$config = $dotEnv->loadPrivate('/path/to/app');

// DB_PASSWORD → AES-decrypted string
// API_KEY     → Sodium-decrypted string
// PLAIN       → 'no-encryption-needed' (passed through unchanged)

Documentation

Full documentation, guides, and API reference:

docs.jardis.io/en/support/secret

License

This package is licensed under the MIT License.

Jardis · Documentation · Headgent

AI-Assisted Development

This package ships with a skill for Claude Code, Cursor, Continue, and Aider. Install it in your consuming project:

composer require --dev jardis/dev-skills

More details: https://docs.jardis.io/en/skills