README

PHP client library for envmap - an environment variable manager that syncs with remote secret stores (AWS SSM, Vault, GCP, 1Password, Doppler, etc.)

Requirements

PHP 8.1+
envmap installed on the server (go install github.com/binsquare/envmap@latest)
envmap configuration initialized (envmap init --global and envmap init)

Installation

composer require bacarndiaye/envmap-php

Server Setup for envmap

# 1. Install envmap
go install github.com/binsquare/envmap@latest

# 2. Generate encryption key
envmap keygen

# 3. Configure global provider
envmap init --global

# 4. Configure project
envmap init

# 5. Add secrets
envmap set --env dev DATABASE_URL --prompt
envmap set --env dev API_KEY --prompt

Basic Usage

<?php

use Gaindetech\EnvMap\EnvMap;

// Create an instance
$envmap = EnvMap::create()
    ->withEnv('dev')
    ->withCache(true);

// Get a secret
$dbUrl = $envmap->get('DATABASE_URL');

// Get with default value
$debug = $envmap->getOrDefault('DEBUG', 'false');

// Check if a secret exists
if ($envmap->has('API_KEY')) {
    $apiKey = $envmap->get('API_KEY');
}

// Get all secrets
$secrets = $envmap->getAll();

// Set a secret
$envmap->set('NEW_SECRET', 'secret-value');

// Delete a secret
$envmap->delete('OLD_SECRET');

Using Helper Functions

<?php

require 'vendor/autoload.php';

// Get a secret
$dbUrl = envmap_get('DATABASE_URL');

// With default value
$debug = envmap_get('DEBUG', 'false');

// Check existence
if (envmap_has('API_KEY')) {
    // ...
}

// Load into $_ENV and $_SERVER
envmap_load();

// Now you can use getenv()
$dbUrl = getenv('DATABASE_URL');

Factory for Different Environments

<?php

use Gaindetech\EnvMap\EnvMapFactory;

// For development
$envmap = EnvMapFactory::forDev();

// For staging
$envmap = EnvMapFactory::forStaging();

// For production
$envmap = EnvMapFactory::forProduction();

// Auto-detect based on APP_ENV or ENV
$envmap = EnvMapFactory::fromEnvironment();

Sync with .env File

<?php

use Gaindetech\EnvMap\EnvMap;

$envmap = EnvMap::create()->withEnv('dev');

// Sync to a .env file
$envmap->sync('.env');

// With options
$envmap->sync(
    outputPath: '.env',
    merge: true,      // Keep local-only keys
    keepLocal: false, // Provider wins on conflict
    force: true,      // Ignore git warnings
    backup: true      // Create .env.bak
);

// Check for differences without writing
$drift = $envmap->checkDrift('.env');
if ($drift['has_drift']) {
    foreach ($drift['differences'] as $key => $diff) {
        echo "$key: file={$diff['file']} provider={$diff['provider']}\n";
    }
}

Import an Existing .env File

<?php

$envmap = EnvMap::create()->withEnv('dev');

// Import secrets from a .env file
$envmap->import('.env.local');

// Import and delete source file
$envmap->import('.env.local', deleteAfter: true);

Laravel Integration

Installation

Add the service provider in config/app.php (or use auto-discovery):

'providers' => [
    Gaindetech\EnvMap\Laravel\EnvMapServiceProvider::class,
],

'aliases' => [
    'EnvMap' => Gaindetech\EnvMap\Laravel\Facades\EnvMap::class,
],

Publish Configuration

php artisan vendor:publish --tag=envmap-config

Configuration (config/envmap.php)

return [
    'binary_path' => env('ENVMAP_BINARY_PATH'),
    'env' => env('ENVMAP_ENV'),           // or auto-detected from APP_ENV
    'project_config' => env('ENVMAP_PROJECT_CONFIG'),
    'cache' => env('ENVMAP_CACHE', true),
    'auto_load' => env('ENVMAP_AUTO_LOAD', false),
];

Usage

<?php

use Gaindetech\EnvMap\Laravel\Facades\EnvMap;

// Via Facade
$dbUrl = EnvMap::get('DATABASE_URL');
$all = EnvMap::getAll();
EnvMap::set('KEY', 'value');

// Via dependency injection
use Gaindetech\EnvMap\EnvMap;

class MyController
{
    public function __construct(private EnvMap $envmap) {}

    public function index()
    {
        $secret = $this->envmap->get('API_KEY');
    }
}

Auto-load Secrets

In .env or config/envmap.php, enable auto-load:

ENVMAP_AUTO_LOAD=true

This automatically loads all secrets into $_ENV on startup, allowing you to use env() normally.

Symfony Integration

Installation

Add the bundle in config/bundles.php:

return [
    Gaindetech\EnvMap\Symfony\EnvMapBundle::class => ['all' => true],
];

Configuration (config/packages/envmap.yaml)

envmap:
    binary_path: ~          # null = auto-detect
    env: '%kernel.environment%'
    project_config: ~
    cache: true
    auto_load: false

Usage

<?php

use Gaindetech\EnvMap\EnvMap;

class MyService
{
    public function __construct(private EnvMap $envmap) {}

    public function doSomething(): void
    {
        $apiKey = $this->envmap->get('API_KEY');
    }
}

Error Handling

<?php

use Gaindetech\EnvMap\EnvMap;
use Gaindetech\EnvMap\Exception\SecretNotFoundException;
use Gaindetech\EnvMap\Exception\EnvMapException;
use Gaindetech\EnvMap\Exception\ConfigurationException;

$envmap = EnvMap::create()->withEnv('dev');

try {
    $secret = $envmap->get('NON_EXISTENT_KEY');
} catch (SecretNotFoundException $e) {
    // Secret does not exist
    echo "Secret not found: " . $e->getMessage();
} catch (ConfigurationException $e) {
    // envmap configuration problem
    echo "Configuration error: " . $e->getMessage();
} catch (EnvMapException $e) {
    // Other envmap error
    echo "Error: " . $e->getMessage();
}

Custom Binary Path

<?php

use Gaindetech\EnvMap\EnvMap;

// Custom path to envmap
$envmap = EnvMap::create('/usr/local/bin/envmap');

// Or via environment variable
putenv('ENVMAP_BINARY_PATH=/custom/path/envmap');

Cache

<?php

use Gaindetech\EnvMap\EnvMap;

// Enable cache (recommended in production)
$envmap = EnvMap::create()
    ->withEnv('prod')
    ->withCache(true);

// Repeated calls to get() use the cache
$value1 = $envmap->get('KEY'); // Calls envmap
$value2 = $envmap->get('KEY'); // From cache

// Clear cache manually
$envmap->clearCache();

Complete API

EnvMap

Method	Description
`create(?string $binaryPath)`	Create an instance
`withEnv(string $env)`	Set the environment
`withProjectConfig(string $path)`	Set the project config file
`withCache(bool $enabled)`	Enable/disable cache
`get(string $key)`	Get a secret
`getAll()`	Get all secrets
`getOrDefault(string $key, string $default)`	Get with fallback
`has(string $key)`	Check if a secret exists
`set(string $key, string $value)`	Set a secret
`delete(string $key)`	Delete a secret
`sync(...)`	Sync to .env file
`checkDrift(string $envFilePath)`	Check for differences
`import(string $filePath, bool $deleteAfter)`	Import a .env file
`validate()`	Validate configuration
`loadIntoEnvironment(bool $overwrite)`	Load into $_ENV
`clearCache()`	Clear the cache

Helper Functions

Function	Description
`envmap(?string $key, mixed $default)`	Get a secret or the instance
`envmap_get(string $key, mixed $default)`	Get a secret
`envmap_has(string $key)`	Check existence
`envmap_all()`	Get all secrets
`envmap_load(bool $overwrite)`	Load into $_ENV

License

MIT License. See LICENSE for more details.

bacarndiaye / envmap-php

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Server Setup for envmap

Basic Usage

Using Helper Functions

Factory for Different Environments

Sync with .env File

Import an Existing .env File

Laravel Integration

Installation

Publish Configuration

Configuration (config/envmap.php)

Usage

Auto-load Secrets

Symfony Integration

Installation

Configuration (config/packages/envmap.yaml)

Usage

Error Handling

Custom Binary Path

Cache

Complete API

EnvMap

Helper Functions

License