README

A modern, flexible secrets management library for PHP applications with a fluent builder API and multiple storage backends.

Features

• Fluent Builder API - Intuitive, chainable methods for configuration
• Multiple Storage Backends - File-based and environment-based key storage
• Secure Encryption - Built on Halite/libsodium for authenticated encryption
• Vault Management - Organize secrets into isolated vaults
• Key Rotation - Generate and manage cryptographic keys with ease
• File & Message Encryption - Encrypt data of any size
• Zero Configuration - Sensible defaults with full customization

Installation

composer require paradisesecurity/secrets-manager

Quick Start

Basic Usage

use ParadiseSecurity\Component\SecretsManager\Builder\SecretsManagerBuilder;
use ParadiseSecurity\Component\SecretsManager\Key\Key;
use ParagonIE\HiddenString\HiddenString;

// Create authentication key
$authKey = new Key(
    new HiddenString('your-secure-auth-key'),
    'symmetric_authentication_key',
    'halite',
    '5.0.0'
);

// Build the secrets manager
$secretsManager = SecretsManagerBuilder::create()
    ->withAuthKey($authKey)
    ->withPaths('/path/to/project')
    ->withDefaultVault('production')
    ->configureStorage(fn($builder) => 
        $builder
            ->useMasterKeyStorage('env')
            ->withEnvFile('.env')
    )
    ->build();

// Create a vault
$secretsManager->newVault('production');

// Store secrets
$secretsManager->set('database_password', 'super_secret_password');
$secretsManager->set('api_key', 'sk-1234567890abcdef');

// Retrieve secrets
$dbPassword = $secretsManager->get('database_password');
$apiKey = $secretsManager->get('api_key');

Advanced Configuration

$secretsManager = SecretsManagerBuilder::create()
    ->withAuthKey($authKey)
    ->withKeyringName('production-keyring')
    ->withDefaultVault('app-secrets')
    ->withPaths('/var/www/project', '/var/www/project/config/secrets')
    ->configureEncryption(fn($builder) => 
        $builder->useAdapter('halite')
    )
    ->configureStorage(fn($builder) => 
        $builder
            ->useMasterKeyStorage('env')
            ->withEnvFile('.env.production')
    )
    ->configureVault(fn($builder) => 
        $builder->withCache(true, 'secrets-cache')
    )
    ->build();

Architecture

The Secrets Manager is built around a modular architecture with independent builders:

• EncryptionBuilder - Configure encryption adapters and key generation
• StorageBuilder - Manage filesystem paths and key storage mechanisms
• VaultBuilder - Configure vault adapters with optional caching
• KeyManagerBuilder - Coordinate key generation and management
• SecretsManagerBuilder - Orchestrate all components into a unified API

Each builder can be used independently or composed together for full functionality.

Storage Options

File-Based Storage

Keys are stored as encrypted files in the filesystem:

$builder->configureStorage(fn($b) => 
    $b->useMasterKeyStorage('file')
);

Environment-Based Storage

Keys are stored in .env files for easy deployment:

$builder->configureStorage(fn($b) => 
    $b->useMasterKeyStorage('env')
      ->withEnvFile('.env.secrets')
);

Documentation

Comprehensive documentation is available in the docs folder:

• Installation Guide
• Architecture Overview
• Builder Pattern Guide
• Storage Systems
• Encryption Guide
• Key Management
• Vault Management
• Examples & Recipes

Requirements

• PHP 8.1 or higher
• paragonie/halite ^5.0
• paragonie/hidden-string ^2.0
• symfony/options-resolver ^6.0|^7.0
• league/flysystem ^3.0

Development Status

⚠️ This library is currently in active development. APIs may change before the first stable release. Not recommended for production use yet.

Testing

composer install
vendor/bin/phpunit

Security

If you discover any security vulnerabilities, please email security@paradisesecurity.work instead of using the issue tracker.

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

• Created by Paradise Security
• Inspired by Secretary for PHP
• Built with Halite cryptography library

Paradise Security - Building secure, decoupled PHP components with the highest quality code.