README

Easily integrate HashiCorp Vault secrets into your Laravel project with zero friction. This package allows you to manage secrets via Vault while maintaining Laravel's native config('...') access style — just like you would with .env files.

What is HashiCorp Vault?

HashiCorp Vault is a tool for securely storing and accessing tokens, passwords, certificates, encryption keys, and other sensitive data. Kindly see More Here: https://github.com/hashicorp/vault-guides

🚀 Why Use This Package?

Managing secrets in Laravel shouldn't require rewriting your entire application just to integrate with HashiCorp Vault. This package was built to solve one simple but powerful problem:

✅ Seamlessly upgrade from .env-based config to Vault-based secret management — without touching how your app reads secrets.

If you're using Laravel’s config('app.secret_key') or similar patterns, this package lets you continue doing that while the underlying secrets are pulled from Vault securely.

🔍 What Makes This Package Different?

🧩 1. Plug-and-Play with Laravel’s Config System

You don't need to rewrite your codebase. Just map your Vault keys to Laravel config keys, and call them as you always have:

config('app.my_api_key')

⚙️ 2. Two Powerful Modes of Integration

Mode	Description
File Mode	Read secrets from one or more Vault-agent-generated files (supporting `.env`, `.txt`, `.json`, and more) — perfect for agent setups or Docker environments.
Token Mode	Pull secrets directly from the Vault server using a token, supporting multiple paths and tokens. Great for dynamic secret retrieval.

🧠 3. Configurable, Flexible, and Cache-Aware

Supports multiple file paths or multiple Vault token sources
Maps secrets to Laravel config effortlessly
Uses Laravel's cache system to improve performance

🪄 4. Transition-First Design

Unlike other packages that require rigid integration styles or special syntax, this one was designed with real-world Laravel projects in mind — allowing teams to migrate without friction, allowing keys to be called using the default Laravel config() mechanism.

📦 Installation

composer require thetribeofdan/laravel_vault

If you want to publish the config file:

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

You'll now see a config/vault.php file. This is your main control centre 🧠

🛠️ Configuration

1. Choose your mode

Set the mode in .env or directly in config/vault.php:

VAULT_MODE=file     # or 'token'

2. File Mode (📁 Local Files)

Use this when you want to load secrets from one or more files generated by the Vault Agent or by yourself on your Server (e.g. .env, .json):

'file_paths' => [
    base_path('.vault/secrets.env'),
    base_path('.vault/extra.json'),
],

✅ Supported formats:

.env-style: KEY=value
.json-style: { "KEY": "value" }

3. Token Mode (🔐 Live HashiCorp Vault)

Use this when you want to connect to a live Vault instance using the Auth token:

'token_sources' => [
    [
        'token' => env('VAULT_TOKEN'),
        'path'  => '/v1/secret/data/app',
        'url'   => env('VAULT_URL'),
    ],
    [
        'token' => env('VAULT_ALT_TOKEN'),
        'path'  => '/v1/secret/data/billing',
        'url'   => env('VAULT_URL'),
    ],
],

📌 Supports multiple tokens, engine paths and URLs.

4. Mapping Secrets to Config 🗺️

Map secrets from your files or Vault into Laravel config using the map array in your config/vault.php file:

'app.app_key' => 'APP_KEY',
'app.mailgun.secret' => 'MAILGUN_SECRET',

Usage in your Project’s code:

config('app.app_key');
config('app.mailgun.secret');

🔁 Refreshing Secrets at Runtime

Need to reload your secrets on the fly (e.g. after token rotation or file update)? Just call:

Vault::refresh();

To force a reload and cache refresh of Vault secrets.

⚠️ Laravel Cache Warning

If you're using database cache driver, make sure to run the default cache migration:

php artisan cache:table
php artisan migrate

Or switch to file or redis temporarily.

💡 Tips

Make sure you run Laravel's php artisan cache:table & migrate if using database cache
All secrets are cached for 1 hour by default (configurable)
This package is best used for secure, centralized secrets

Tutorials/Video Walkthrough

Installation and Configuration https://youtu.be/7ofXmhYIKmM?si=1D7Ad5QiQ5FcGOnX

🙌 Credits

Built with 🖤 by Daniel Fiyinfoluwa Egbeleke aka The Bad Guy™. Inspired by a personal need to make secure secret integration feel effortless for my Future Projects...Hope You Like It 🔐

💖 Support the Project

If this package saved you hours or helped secure your Laravel app, consider sponsoring the project:

👉 Donate via Flutterwave
🫶 Every contribution goes towards maintaining, improving, and supporting this tool for the community.

Massive Help by @imambash6

thetribeofdan / laravel_vault

Maintainers

Details