PHPackages                             shahkochaki/laravel-vault - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. shahkochaki/laravel-vault

ActiveLibrary[DevOps & Deployment](/categories/devops)

shahkochaki/laravel-vault
=========================

🔐 Complete HashiCorp Vault integration for Laravel - Auto-sync secrets from Vault to your .env, seamless KV v2 support, production-ready caching, Vault Agent authentication, and zero-config secret management. Keep your credentials safe and your deployments simple.

1.4.1(5mo ago)351MITPHPPHP ^8.0

Since Dec 9Pushed 5mo agoCompare

[ Source](https://github.com/shahkochaki/laravel-vault-pro)[ Packagist](https://packagist.org/packages/shahkochaki/laravel-vault)[ Docs](https://github.com/shahkochaki/laravel-vault-pro)[ RSS](/packages/shahkochaki-laravel-vault/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (13)Used By (0)

🔐 Laravel Vault - Complete HashiCorp Vault Integration
======================================================

[](#-laravel-vault---complete-hashicorp-vault-integration)

[![Latest Version](https://camo.githubusercontent.com/7df6c8582d168ecd4b93f95332ca62a3c0d59a491fc579b35375b28595db28a0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736861686b6f6368616b692f6c61726176656c2d7661756c742e737667)](https://packagist.org/packages/shahkochaki/laravel-vault)[![Total Downloads](https://camo.githubusercontent.com/7bb07b8c9892e7dd3f4fa835add24b05722b5fa8efef79702c437b2b25a2a7dd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736861686b6f6368616b692f6c61726176656c2d7661756c742e737667)](https://packagist.org/packages/shahkochaki/laravel-vault)[![License](https://camo.githubusercontent.com/5b3971d594d2803f309e74b04eeec964b0ae9fc55df494055b136bb90e656628/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f736861686b6f6368616b692f6c61726176656c2d7661756c742e737667)](https://packagist.org/packages/shahkochaki/laravel-vault)

**The most powerful and developer-friendly HashiCorp Vault integration for Laravel.** Automatically sync secrets, manage credentials securely, and deploy with confidence - all without committing sensitive data to your repository.

✨ Why Laravel Vault?
--------------------

[](#-why-laravel-vault)

Stop managing secrets manually. Let Laravel Vault handle it automatically:

- 🔄 **Auto-sync secrets** from Vault directly to your `.env` file
- 🎯 **Zero-config setup** - works out of the box with sensible defaults
- 🚀 **Production-ready** - built for Kubernetes, Docker, and cloud deployments
- 🔒 **Secure by default** - never commit credentials again
- ⚡ **Smart caching** - fast performance without compromising security
- 🛠️ **Flexible configuration** - adapt to any workflow

🎯 Key Features
--------------

[](#-key-features)

### Core Features

[](#core-features)

- **🔄 Automatic .env Sync**: Reads your `.env`, finds empty keys, and fills them from Vault
- **⚙️ Flexible Control**: Choose to update environment variables, Laravel configs, or both
- **🎨 Custom Mappings**: Define your own mappings between env variables and config paths
- **📦 Full KV v2 Support**: Automatically constructs proper v2 API paths
- **🔑 Vault Agent Ready**: Token-file support for container and Kubernetes environments
- **⚡ Smart Caching**: Configurable caching using Laravel's cache system
- **🎯 Auto Config Injection**: Built-in support for Database, Redis, Mail, AWS, and more
- **🛡️ Error Resilient**: Graceful error handling with detailed logging
- **🔧 Laravel 9-12 Compatible**: Works with all modern Laravel versions

### Built-in Config Mappings

[](#built-in-config-mappings)

Out-of-the-box support for:

- 💾 **Database**: MySQL, PostgreSQL, SQL Server
- 🔴 **Redis**: Connection credentials and settings
- 📧 **Mail**: SMTP, Mailgun, SES configurations
- ☁️ **AWS**: S3, SQS, SNS credentials
- 🔄 **Queue**: Redis, SQS, Beanstalkd
- 💿 **Cache**: Redis, Memcached
- 🔐 **Session**: Database, Redis storage

---

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require shahkochaki/laravel-vault
```

The package uses Laravel's package auto-discovery.

Optionally publish the configuration file:

```
php artisan vendor:publish --provider="Shahkochaki\Vault\VaultServiceProvider" --tag=config
```

This creates `config/vault.php` in your application.

### Environment variables

[](#environment-variables)

Edit your `.env`:

```
# Option A: include port in the address
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=your_vault_token_here
VAULT_ENGINE=secret
VAULT_PATH=app/production
VAULT_SECRET=database

# Option B: provide host and port separately
# VAULT_ADDR may be scheme+host only; set VAULT_PORT to append when building the base URI
VAULT_ADDR=https://vault.example.com
VAULT_PORT=8200
VAULT_TOKEN=your_vault_token_here
VAULT_ENGINE=secret
VAULT_PATH=app/production
VAULT_SECRET=database
```

For production with Vault Agent (recommended):

```
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=
VAULT_TOKEN_FILE=/var/run/secrets/vault-token
VAULT_ENGINE=secret
VAULT_PATH=app/production
VAULT_SECRET=database
```

### 🐳 Docker / Kubernetes Setup

[](#-docker--kubernetes-setup)

**If you're using Docker, Docker Compose, or Kubernetes**, you should use **VAULT mode** instead of the default DOTENV mode. This is because container environments typically don't have a `.env` file and instead use environment variables directly.

#### Docker Compose Example

[](#docker-compose-example)

```
version: "3.8"

services:
  app:
    image: your-laravel-app
    environment:
      # Vault Configuration
      - VAULT_ADDR=http://vault:8200
      - VAULT_TOKEN=${VAULT_TOKEN}
      - VAULT_ENGINE=secret
      - VAULT_PATH=app/production
      - VAULT_SECRET=database

      # Important: Use VAULT sync mode for Docker
      - VAULT_SYNC_MODE=vault

      # Optional: Control what gets updated
      - VAULT_UPDATE_ENV=true
      - VAULT_UPDATE_CONFIG=true
    depends_on:
      - vault

  vault:
    image: vault:latest
    ports:
      - "8200:8200"
```

#### Kubernetes Example

[](#kubernetes-example)

```
apiVersion: v1
kind: ConfigMap
metadata:
  name: laravel-config
data:
  VAULT_ADDR: "http://vault.vault.svc.cluster.local:8200"
  VAULT_ENGINE: "secret"
  VAULT_PATH: "app/production"
  VAULT_SECRET: "database"
  VAULT_SYNC_MODE: "vault" # Important for Kubernetes!

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: laravel-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-laravel-app:latest
          envFrom:
            - configMapRef:
                name: laravel-config
          env:
            - name: VAULT_TOKEN
              valueFrom:
                secretKeyRef:
                  name: vault-token
                  key: token
```

#### Why use `VAULT_SYNC_MODE=vault` for Docker?

[](#why-use-vault_sync_modevault-for-docker)

- ✅ No `.env` file needed in the container
- ✅ Environment variables come from Docker/Kubernetes
- ✅ Vault fills in only the missing/empty variables
- ✅ Perfect for microservices and orchestrated deployments
- ✅ Works seamlessly with CI/CD pipelines

**How it works:**

1. Your orchestrator (Docker/K8s) sets base environment variables
2. Laravel Vault reads all secrets from Vault
3. For each secret, it checks if `env()` is empty
4. Only empty/missing variables are filled from Vault
5. Your existing environment variables are preserved

---

Usage
-----

[](#usage)

The package registers a singleton `Shahkochaki\\Vault\\VaultService` that you can inject, resolve from the container, or use in any Laravel context.

### Simple example — read a secret

[](#simple-example--read-a-secret)

```