README.md

Secretary - Secrets Manager for PHP

Secrets are an important aspect of most applications you can build. How you store them, and keep them "secret" is a challenge. Luckily, there are tools you can use to keep them all safe.

Secretary is a tool to integrate your PHP application with these tools.

Table of Contents

1. Installation
2. Api Documentation
   1. Secretary\Manager
      1. Initializing
      2. getSecret
      3. putSecret
      4. deleteSecret
      5. getAdapter
   2. Secretary\Secret
      1. getKey
      2. getValue

Installation

$ composer req secretary/core

Choose the version you need

Version (X.Y.Z)	PHP	Symfony	Comment
3.*	>= 8.1.0	7.0	Current version
2.*	>= 8.1.0	5.4, 6.0	Previous version
1.*	>= 7.4.0	5.3	Previous version

By itself, the core is useless. You will also need to add at least one adapter:

Storage Engine	Badges
AWS Secrets Manager
HashiCorp Vault
JSON File

There are also miscellaneous packages that add on to Secretary

Package	Purpose	Badges
PSR-6 Cache Adapter	Allows for caching secrets using a PSR-6 Cache Interface
PSR-16 Cache Adapter	Allows for caching secrets using a PSR-16 Cache Interface
Secretary Bundle	Allows for integrating with the Symfony Framework

Api Documentation

There's two classes you interface with in Secretary:

• Secretary\Manager
• Secretary\Secret

Secretary\Manager

Secretary\Manager->__construct(AdapterInterface $adapter)

Pass in your desired adapter.

<?php
use Secretary\Manager;
use Secretary\Adapter\AWS\SecretsManager\LocalJSONFileAdapter;

$manager = new Manager(
    new LocalJSONFileAdapter([
        'region'      => 'us-east-1',
        'credentials' => [
            'accessKeyId'     => 'myAccessKeyId',
            'secretAccessKey' => 'mySecretAccessKey'
        ]
    ])
);

Optionally, you may wrap your adapter, with one of the two cache adapters.

<?php
use Secretary\Manager;
use Secretary\Adapter\AWS\SecretsManager\LocalJSONFileAdapter;

use Secretary\Adapter\Cache\PSR6Cache\ChainAdapter;
use Cache\Adapter\Apc\ApcCachePool;

$manager = new Manager(
    new ChainAdapter(
        new LocalJSONFileAdapter([
            'region'      => 'us-east-1',
            'credentials' => [
                'accessKeyId'     => 'myAccessKeyId',
                'secretAccessKey' => 'mySecretAccessKey'
            ]
        ]),
        new ApcCachePool()
    )
);

For mor information on the arguments and options for the adapters, view their respective documentation.

Secretary\Manager->getSecret(string $key, ?array $options): Secret

Fetches a secret from the configured adapter. $key is the name of the secret (or path) you are trying to get.

Certain adapters will take custom options as well, like VersionId and VersionStage for the AWS SecretsManager Adapter

This will throw a Secretary\SecretNotFoundException if the secret cannot be found

$secret = $manager->getSecret('databases/redis/dsn');
/*
Secret {
    "path" = "databases/redis/dsn",
    "value" = "redis://localhost:6379"
}
*/

Some adapters also support storing a key/value map as a secret's value.

$secret = $manager->getSecret('databases/redis');
/*
Secret {
    "path" = "databases/redis",
    "value" = [
        "dsn" => "redis://localhost:6379",
        "password" => "my_super_strong_password" 
    ]
}
*/

Secretary\Manager->putSecret(string $key, string|array $value, ?array $options): void

Puts a secret with the given $value, into the storage engine, under the given $key.

If the current adapter doesn't support arrays, and you pass one it, it will throw a Secretary\ValueNotSupportedException.

Again, some adapters allow passing in custom options to send along with the request.

$manager->putSecret('database/redis', 'postgres://localhost:5432');

And for adapters that support a key/value map as a value:

$manager->putSecret('database/redis', ['dsn' => 'redis://localhost:6379', 'password' => 'my_super_strong_password']);

Secretary\Manager->deleteSecret(string $key, ?array $options): void

Deletes a secret from the storage engine using the given $key.

Again, some adapters allow passing in custom options to send along with the request.

$manager->deleteSecret('database/redis');

Secretary\Manager->getAdapter(): AdapterInterface

Will return the adapter that was passed to this manager during construction.

Secretary\Secret

This class implements ArrayAccess, so if your secret supports passing a key/value map, you can grab straight from the map:

Secrets are immutable, so attempting to change a value will throw an Exception.

$secret = $manager->getSecret('database/redis');

$dsn = $secret['dsn'];

Secretary\Secret->getKey(): string

Returns the key for the secret

$secret = $manager->getSecret('dabase/redis');

$secret->getKey() === 'database/redis'; // true

Secretary\Secret->getValue(): string | array

Returns the value for the secret. If the secret is a key/value map, its an array

$secret = $manager->getSecret('dabase/redis/dsn');

$secret->getValue() === 'redis://localhost:6379'; // true

// Or

$secret = $manager->getSecret('dabase/redis');

print_r($secret->getValue()); 
/*
[
    "dsn" => "redis://localhost:6379",
    "password" => "my_super_strong_password" 
]
*/