jardissupport / secret

v1.1.0 2026-08-30 06:32 UTC

Requires

• php: >=8.2
• jardissupport/contracts: ^1.0 || ^2.0

Requires (Dev)

• ext-openssl: *
• ext-sodium: *
• phpstan/phpstan: 2.1.56
• phpunit/phpunit: 10.5.63
• squizlabs/php_codesniffer: 3.13.6

Suggests

• ext-openssl: Required for AES-256-GCM encryption (AesSecretResolver)
• ext-sodium: Required for Sodium encryption (SodiumSecretResolver)
• jardissupport/dotenv: Enables transparent secret decryption via the DotEnv cast chain (DotEnv::addHandler())

MIT

• Jardis Development

• php
• encryption
• aes
• environment
• dotenv
• secret
• sodium
• domain-driven-design
• aes-256-gcm
• jardis
• Headgent
• jardisSupport

Published on Packagist.org on 2026-08-30 06:33 UTC

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
• Marker Detection — Secret::matches() answers "is this value a secret(...) marker?" without duplicating the format
• Typed Exceptions — InvalidKeyException, DecryptionFailedException, and EncryptionFailedException 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

Detecting a secret marker

Consumers that need to know whether a raw configuration value carries the secret(...) marker — a bootstrap deciding whether a key file is required, a diagnostics view masking encrypted entries — ask the package instead of copying the regex:

use JardisSupport\Secret\Secret;

Secret::matches('secret(base64encodedEncryptedValue)');  // true
Secret::matches('secret(sodium:base64value)');           // true
Secret::matches('no-encryption-needed');                 // false
Secret::matches('Secret(value)');                        // false — the marker is case-sensitive
Secret::matches('secret()');                             // false — the payload must not be empty

// The expression itself, if you really need it:
Secret::PATTERN;  // '/^secret\((.+)\)$/'

matches() is static and stateless: it applies exactly the rule Secret::__invoke() uses to decide whether to resolve, but touches no resolver, no key and no decryption.

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