PHPackages                             open-laravel/env-guardian - 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. open-laravel/env-guardian

ActiveLibrary

open-laravel/env-guardian
=========================

Keep your Laravel .env.example in sync with .env - safely and non-destructively

1126[1 PRs](https://github.com/open-laravel/env-guardian/pulls)PHPCI passing

Since Dec 26Pushed 1mo agoCompare

[ Source](https://github.com/open-laravel/env-guardian)[ Packagist](https://packagist.org/packages/open-laravel/env-guardian)[ RSS](/packages/open-laravel-env-guardian/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (4)Used By (0)

Env Guardian
============

[](#env-guardian)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e8d19312f3fe287d08833b6521e325fd53cfe0bd5e4bd975fc5d8218fb482a53/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f70656e2d6c61726176656c2f656e762d677561726469616e2e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/e8d19312f3fe287d08833b6521e325fd53cfe0bd5e4bd975fc5d8218fb482a53/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f70656e2d6c61726176656c2f656e762d677561726469616e2e7376673f7374796c653d666c61742d737175617265)[![GitHub Tests Action Status](https://camo.githubusercontent.com/41836cb2bcdfdecbf960dfba3ce67624ffd82a5b0c9279bffa6bb06059cd00f5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f70656e2d6c61726176656c2f656e762d677561726469616e2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/open-laravel/env-guardian/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/2d5a371ca3b79a734d6082917ebb5b051a63de20b346c01e7d8af45a54e9def3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f70656e2d6c61726176656c2f656e762d677561726469616e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/open-laravel/env-guardian)

**Env Guardian** helps Laravel teams keep `.env.example` in sync with `.env` files - safely and non-destructively.

Features
--------

[](#features)

✅ **Safe & Non-Destructive** - Never removes or overwrites existing keys
✅ **Git Hook Integration** - Non-blocking pre-commit warnings
✅ **Multiple Commands** - Sync, diff, check, discover env keys
✅ **CI/CD Ready** - Perfect for automated checks
✅ **Laravel 9+** - Supports Laravel 9, 10, 11, and 12
✅ **PHP 8.1+** - Modern PHP support

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

[](#installation)

You can install the package via composer:

```
composer require open-laravel/env-guardian
```

Publish the config file:

```
php artisan vendor:publish --tag=env-guardian-config
```

This will create a `config/env-guardian.php` file with the following options:

```
return [
    'required_keys' => [],           // Keys that must be present in .env
    'mask_values' => true,           // Whether to mask values in .env.example
    'mask_with' => '',               // Mask value (empty or 'changeme')
    'grouped' => false,              // Group keys by prefix
    'ci_fail_on_error' => true,      // Fail in CI mode if required keys missing
];
```

Usage
-----

[](#usage)

### 1. Sync Missing Keys

[](#1-sync-missing-keys)

Sync keys from `.env` to `.env.example`:

```
php artisan env:sync-example
```

**Options:**

- `--dry-run` - Preview changes without writing
- `--sort` - Sort keys alphabetically
- `--grouped` - Group keys with comment headers
- `--mask-value=` - Custom mask value (default: empty)

**Example:**

```
# Preview changes
php artisan env:sync-example --dry-run

# Sync and sort keys
php artisan env:sync-example --sort

# Sync with grouped output
php artisan env:sync-example --grouped

# Use custom mask value
php artisan env:sync-example --mask-value=changeme
```

### 2. Compare Env Files

[](#2-compare-env-files)

Compare `.env` and `.env.example` to see differences:

```
php artisan env:diff
```

**Options:**

- `--quiet` - Minimal output for CI/scripting

**Example:**

```
# Show full diff
php artisan env:diff

# Quiet mode for scripts
php artisan env:diff --quiet
```

### 3. Check Required Keys

[](#3-check-required-keys)

Check if required environment keys are present:

```
php artisan env:check
```

**Options:**

- `--ci` - Exit with non-zero code if keys are missing (for CI/CD)

**Example:**

```
# Check required keys
php artisan env:check

# CI mode
php artisan env:check --ci
```

Configure required keys in `config/env-guardian.php`:

```
'required_keys' => [
    'APP_KEY',
    'APP_URL',
    'DB_CONNECTION',
    'DB_HOST',
    'DB_DATABASE',
],
```

### 4. Install Git Hook

[](#4-install-git-hook)

Install a non-blocking pre-commit hook:

```
php artisan env:install-hook
```

**Options:**

- `--force` - Overwrite existing hook
- `--uninstall` - Remove the hook

The hook will:

- ✅ Warn about missing keys in `.env.example`
- ✅ **NOT** block commits (always exits 0)
- ✅ Suggest running `env:sync-example`

**Example:**

```
# Install hook
php artisan env:install-hook

# Force overwrite existing hook
php artisan env:install-hook --force

# Uninstall hook
php artisan env:install-hook --uninstall
```

### 5. Discover Env Usage

[](#5-discover-env-usage)

Scan your code for `env()` usage:

```
php artisan env:discover
```

**Options:**

- `--write` - Write discovered keys to `.env.example`
- `--mask-value=` - Custom mask value

This command scans:

- `config/` directory
- `app/` directory
- `routes/` directory

**Example:**

```
# Discover keys
php artisan env:discover

# Discover and write to .env.example
php artisan env:discover --write
```

CI/CD Integration
-----------------

[](#cicd-integration)

### GitHub Actions

[](#github-actions)

```
name: Check Environment

on: [push, pull_request]

jobs:
  env-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
      - run: composer install
      - run: php artisan env:check --ci
      - run: php artisan env:diff --quiet
```

### GitLab CI

[](#gitlab-ci)

```
env-check:
  script:
    - composer install
    - php artisan env:check --ci
    - php artisan env:diff --quiet
```

Best Practices
--------------

[](#best-practices)

1. **Always run `env:sync-example`** before committing
2. **Use `env:check --ci`** in your CI pipeline
3. **Install the Git hook** for automatic warnings
4. **Run `env:discover`** periodically to catch new env usage
5. **Configure required keys** for critical environment variables

How It Works
------------

[](#how-it-works)

### Parsing

[](#parsing)

- Reads `.env` and `.env.example` files directly from filesystem
- Parses `KEY=VALUE` pairs manually (does NOT use `env()` helper)
- Ignores comments (`#`) and empty lines
- Supports quoted values (`"value"` or `'value'`)
- Handles `export KEY=value` syntax

### Syncing

[](#syncing)

- **NEVER removes** keys from `.env.example`
- **NEVER overwrites** existing keys
- Appends new keys at the bottom
- Preserves all comments and formatting
- Idempotent (running twice produces no changes)

### Git Hook

[](#git-hook)

- Installed in `.git/hooks/pre-commit`
- **Non-blocking** (always exits 0)
- Shows warning if keys are missing
- Suggests running `env:sync-example`
- Can be removed anytime

Example Workflow
----------------

[](#example-workflow)

```
# 1. Add new env var to .env
echo "NEW_API_KEY=secret123" >> .env

# 2. Check what's different
php artisan env:diff

# 3. Sync to .env.example
php artisan env:sync-example

# 4. Commit changes
git add .env.example
git commit -m "Add NEW_API_KEY to env.example"
```

Testing
-------

[](#testing)

```
composer test
```

Code Quality
------------

[](#code-quality)

```
# Format code
composer format

# Static analysis
composer analyse
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Open Laravel](https://github.com/open-laravel)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance59

Moderate activity, may be stable

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity17

Early-stage or recently created project

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/a3eb612c73955906d7cee5fa6f08350ea70292f7f81421d5a96c8279fa410a36?d=identicon)[code-tieumomo](/maintainers/code-tieumomo)

---

Top Contributors

[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (9 commits)")[![code-tieumomo](https://avatars.githubusercontent.com/u/81463452?v=4)](https://github.com/code-tieumomo "code-tieumomo (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

### Embed Badge

![Health badge](/badges/open-laravel-env-guardian/health.svg)

```
[![Health](https://phpackages.com/badges/open-laravel-env-guardian/health.svg)](https://phpackages.com/packages/open-laravel-env-guardian)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)