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

Helper Functions

License

MIT License. See LICENSE for more details.