PHPackages                             scoult/secrets - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. scoult/secrets

ActiveLibrary[Utility & Helpers](/categories/utility)

scoult/secrets
==============

A provider-agnostic PHP package to access secrets from various sources (e.g. Azure App Configuration, Env, Array).

00PHP

Since Jun 20Pushed todayCompare

[ Source](https://github.com/scoult/secrets)[ Packagist](https://packagist.org/packages/scoult/secrets)[ RSS](/packages/scoult-secrets/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Unified Secrets Access for PHP (`scoult/secrets`)
=================================================

[](#unified-secrets-access-for-php-scoultsecrets)

A lightweight, provider-agnostic PHP library to fetch configuration secrets from a variety of sources. Your application logic remains clean and decouples itself from the secret engine (e.g. Microsoft Azure App Configuration, Environment Variables, or Vaults).

---

Features
--------

[](#features)

- **Provider-agnostic interface** (`SecretsProviderInterface`) so your app logic doesn't care where secrets come from.
- **Out-of-the-box Microsoft Azure App Configuration** provider with HMAC authentication.
- **Azure Key Vault Resolution**: Seamlessly resolves `@Microsoft.KeyVault` secret references inside Azure App Configuration when paired with `AzureKeyVaultResolver`.
- **Environment Variable Provider** with automatic key normalization (e.g., `database.password` mapping to `DATABASE_PASSWORD`).
- **Chain of Responsibility provider** to implement robust lookup fallbacks.
- **Cache Decorator** conforming to PSR-16 (`Psr\SimpleCache\CacheInterface`) to minimize HTTP roundtrips, reduce latency, and lower Azure billing.
- **Modern PHP** design complying with PSR-4, PSR-17, and PSR-18 standards.

---

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require scoult/secrets
```

Ensure you have a PSR-18 HTTP client (e.g., Guzzle) installed in your project:

```
composer require guzzlehttp/guzzle guzzlehttp/psr7
```

---

Usage
-----

[](#usage)

### 1. Azure App Configuration Provider

[](#1-azure-app-configuration-provider)

This provider connects to Azure App Configuration directly using a standard connection string and uses the REST API authenticated via HMAC-SHA256 signatures.

```
use Scoult\Secrets\Providers\AzureAppConfigurationProvider;

// Instantiate the provider with your connection string
$connectionString = 'Endpoint=https://your-store.azconfig.io;Id=your-access-key-id;Secret=your-base64-secret';
$provider = new AzureAppConfigurationProvider($connectionString);

// Retrieve a configuration variable
$dbPassword = $provider->get('database.password');
```

#### Specifying Labels

[](#specifying-labels)

Azure App Configuration allows keys to be tagged with labels. You can target specific labels via the options array:

```
$prodPassword = $provider->get('database.password', ['label' => 'production']);
```

---

### 2. Auto-resolving Key Vault References

[](#2-auto-resolving-key-vault-references)

If your Azure App Configuration contains references to Azure Key Vault secrets (e.g., values stored with the content type `application/vnd.microsoft.appconfig.keyvaultref+json`), you can inject `AzureKeyVaultResolver` to automatically fetch and resolve those secrets:

```
use Scoult\Secrets\Providers\AzureAppConfigurationProvider;
use Scoult\Secrets\Resolvers\AzureKeyVaultResolver;

// Provide a mechanism to supply/retrieve your Entra ID/Bearer Token
$tokenProvider = function () {
    // Return a fresh token (e.g. from Cache, Azure Identity SDK, or OAuth client)
    return 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d...';
};

// Create the resolver
$keyVaultResolver = new AzureKeyVaultResolver($tokenProvider);

// Pass the resolver to the App Configuration provider
$provider = new AzureAppConfigurationProvider(
    $connectionString,
    null, // Auto-discovers Guzzle Client
    null, // Auto-discovers Guzzle Request Factory
    null, // Auto-discovers Guzzle Stream Factory
    $keyVaultResolver
);

// If database.password points to Key Vault, it will automatically dereference and return the secret value
$secretValue = $provider->get('database.password');
```

---

### 3. AWS Secrets Manager Provider

[](#3-aws-secrets-manager-provider)

This provider integrates with AWS Secrets Manager. It accepts either an instance of `Aws\SecretsManager\SecretsManagerClient` or a configuration array directly.

```
use Aws\SecretsManager\SecretsManagerClient;
use Scoult\Secrets\Providers\AwsSecretsManagerProvider;

// 1. Initialize using configuration array
$provider = new AwsSecretsManagerProvider([
    'region' => 'us-west-2',
    'version' => '2017-10-17'
]);

// 2. Fetch standard string secret
$apiKey = $provider->get('my-api-key');

// 3. Fetch from nested JSON secrets
// If 'my-db-secrets' stores a JSON string: {"username": "admin", "password": "xyz"}
// You can retrieve sub-keys using colon syntax or options array:
$dbPassword = $provider->get('my-db-secrets:password');

// Alternatively:
$dbPassword = $provider->get('my-db-secrets', ['key' => 'password']);
```

---

### 4. Combining Providers with `ChainSecretsProvider`

[](#4-combining-providers-with-chainsecretsprovider)

Chain multiple providers together. For example, check local environment variables first, falling back to Azure App Configuration:

```
use Scoult\Secrets\Providers\ChainSecretsProvider;
use Scoult\Secrets\Providers\EnvSecretsProvider;
use Scoult\Secrets\Providers\AzureAppConfigurationProvider;

$chain = new ChainSecretsProvider([
    new EnvSecretsProvider(), // Checks $_ENV / getenv() first
    new AzureAppConfigurationProvider($connectionString) // Fallback
]);

// If DATABASE_PASSWORD is set in environment, returns that. Otherwise, queries Azure.
$dbPassword = $chain->get('database.password');
```

---

### 5. Performance Optimization via Caching

[](#5-performance-optimization-via-caching)

Repeated HTTP requests to Azure App Configuration on every script execution can impact performance and increase costs. Wrap your provider in `CachedSecretsProvider` using any PSR-16 cache:

```
use Scoult\Secrets\Providers\AzureAppConfigurationProvider;
use Scoult\Secrets\Providers\CachedSecretsProvider;

$azureProvider = new AzureAppConfigurationProvider($connectionString);

// Wrap the provider in CachedSecretsProvider with your PSR-16 cache instance
// Defaults to 1 hour (3600 seconds) cache TTL.
$provider = new CachedSecretsProvider($azureProvider, $psr16Cache, 3600);

// First call: Makes HTTP request to Azure
$val = $provider->get('my.secret');

// Subsequent calls: Read from cache directly
$val = $provider->get('my.secret');
```

---

Exception Handling
------------------

[](#exception-handling)

All provider-specific exceptions inherit from `Scoult\Secrets\Exceptions\SecretProviderException`.

```
use Scoult\Secrets\Exceptions\SecretProviderException;

try {
    $secret = $provider->get('database.password');
} catch (SecretProviderException $e) {
    // Handle request failure, unauthorized credentials, or connection issues
    error_log("Failed to fetch secret: " . $e->getMessage());
}
```

---

License
-------

[](#license)

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/54689220?v=4)[Sam Coulter](/maintainers/samcoult)[@samcoult](https://github.com/samcoult)

---

Top Contributors

[![125-sam-coult](https://avatars.githubusercontent.com/u/139442626?v=4)](https://github.com/125-sam-coult "125-sam-coult (2 commits)")

### Embed Badge

![Health badge](/badges/scoult-secrets/health.svg)

```
[![Health](https://phpackages.com/badges/scoult-secrets/health.svg)](https://phpackages.com/packages/scoult-secrets)
```

###  Alternatives

[elhebert/laravel-sri

Subresource Integrity hash generator for laravel

39241.9k](/packages/elhebert-laravel-sri)[mtdowling/burgomaster

Packages up PHP packages into zips and phars

2780.9k12](/packages/mtdowling-burgomaster)[francescomalatesta/laravel-circuit-breaker

A circuit breaker pattern implementation for the Laravel framework

2919.2k2](/packages/francescomalatesta-laravel-circuit-breaker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)