Download the PHP package gause/laravel-keyring without Composer

Laravel Keyring

A driver-based secret manager for Laravel. Injects secrets from your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) into your Laravel environment at runtime — no secrets ever written to disk.

Works seamlessly with Laravel Herd.

The Problem

Local development secrets are a pain. You have .env files with database passwords, API keys, and tokens sitting in plaintext on your filesystem. They get accidentally committed, shared in Slack, or lost when switching machines.

Laravel Keyring solves this by storing your secrets in your operating system's native credential manager and injecting them into Laravel's environment at boot time. Your .env file only needs placeholder values — the real secrets live in your OS keychain.

Installation

The package auto-discovers its service provider. To publish the config file:

Quick Start

1. Store a secret

Or with the value inline:

2. Use it in your app

Your secrets are automatically injected into $_ENV, $_SERVER, and putenv() at boot time. This means env('DB_PASSWORD') just works — even with Laravel Herd.

You can also access secrets directly:

3. List your stored secrets

This shows key names only — never values.

Drivers

Note: OS-native drivers (Keychain, Secret Service, WinCred) store secrets under a namespace derived from your APP_NAME environment variable (defaults to Laravel). This means each project has its own isolated set of secrets. If you rename APP_NAME, previously stored secrets won't be accessible under the new name. You can override the namespace explicitly via the KEYRING_NAMESPACE env variable. File-based drivers (env, json) don't use the namespace — they are scoped by file path.

macOS Keychain (default on macOS)

Uses the native security CLI to store secrets in your login keychain. Secrets are stored as generic passwords with the service name {namespace}.{KEY}. (To inspect them manually, open Keychain Access — not the Passwords app.)

Linux Secret Service (default on Linux)

Uses secret-tool (gnome-keyring / KWallet) to store secrets. Requires the secret-tool package to be installed.

Windows Credential Manager (default on Windows)

Uses cmdkey and PowerShell to store secrets in the Windows Credential Manager.

Env File Driver

Reads/writes a separate .env.secrets file. Useful for CI/CD, Docker, or teammates without OS keychain setup.

JSON Driver

Stores secrets in an encrypted JSON file at storage/.keyring. Uses Laravel's Crypt facade for encryption.

Laravel Herd Setup

Laravel Herd doesn't load .env files the same way as php artisan serve. Keyring bridges this gap by injecting secrets directly into the PHP environment at boot time.

1. Store your secrets in the keychain:

2. In your .env, leave the values empty or use placeholders:

3. Ensure env injection is enabled (it is by default):

That's it. Keyring will inject the real values from your keychain before Laravel reads the config.

Laravel Valet Setup

The setup is the same as Laravel Herd. If Keyring doesn't resolve your secrets from the keychain (returns null), it's likely because Valet starts PHP-FPM as root via sudo. Root has no access to your user's login keychain. Herd doesn't have this problem because it runs as a native macOS app in your user session.

To fix this, run PHP-FPM under your user instead of root — never use sudo when starting PHP via Homebrew services:

After this, Valet's PHP-FPM workers run as your user and can access the login keychain normally.

Artisan Commands

keyring:get {key}

Retrieve and display a secret value.

keyring:set {key} {value?}

Store a secret. If value is omitted, you'll be prompted with hidden input.

keyring:forget {key}

Delete a secret (with confirmation).

keyring:list

List all stored key names (never values).

keyring:import {--file=.env}

Import secrets from a .env file. You'll be prompted to select which keys to import.

Env Injection

By default, Keyring injects all stored secrets into the environment at boot time. You can control this behavior:

Important: Keyring never overwrites environment variables that are already set. If DB_PASSWORD is already present in $_ENV, Keyring won't touch it.

Performance

Env injection runs shell commands on every request. For OS-native drivers (Keychain, Secret Service, WinCred), listing explicit keys is significantly faster than discovering all secrets:

Benchmarked on macOS Keychain. Each key adds ~25ms (one shell call to security find-generic-password).

For best performance, always list your keys explicitly:

Caching

For applications where ~25ms per key per request is too much overhead, Keyring provides an opt-in caching layer. Once enabled, resolved secrets are cached and subsequent requests skip the shell calls entirely.

Cache drivers:

Secrets are only ever cached in RAM — never written to disk. The APCu driver requires the APCu extension. If APCu is not available, caching is silently disabled and a warning is logged.

Installing APCu with Laravel Herd:

Herd ships with its own PHP binaries, so you need to compile the extension via Homebrew and register it in Herd's php.ini. See the Herd PHP Extensions docs for full details.

Cache commands:

Alternatives to caching: If you use php artisan config:cache, Laravel bakes resolved env() values into the cached config file — so secrets are only resolved once. Similarly, Laravel Octane keeps the application in memory, so secrets are resolved once per worker boot. In these setups, you may not need caching at all.

Community Drivers

You can register custom drivers using the extend() method, similar to Laravel Socialite:

Your custom driver must implement Keyring\Contracts\Driver:

Then use it:

Configuration Reference

Testing

Security

• Secrets stored in OS keychains are protected by your user account and OS security mechanisms
• The JSON driver encrypts values using Laravel's APP_KEY via Crypt::encryptString()
• The cache layer (APCu) stores values in RAM only — secrets are never written to disk
• Env injection never overwrites already-set environment variables
• The keyring:list command never displays secret values
• Add .env.secrets and storage/.keyring to your .gitignore

If you discover a security vulnerability, please email [email protected] instead of opening an issue.

Changelog

Please see CHANGELOG for recent changes.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.