mahbubhelal / sync-env
A laravel package to sync env variables between different .env files.
Requires
- php: ^8.5
- illuminate/console: ^13.35
- illuminate/support: ^13.35
Requires (Dev)
- driftingly/rector-laravel: ^2.7
- larastan/larastan: ^3.13
- laravel/pint: ^1.32.1
- orchestra/testbench: ^11.3
- pestphp/pest: ^5.3.4
- pestphp/pest-plugin-laravel: ^5.0.1
- pestphp/pest-plugin-phpstan: ^5.2.2
- pestphp/pest-plugin-rector: ^5.0.6
- pestphp/pest-plugin-type-coverage: ^5.0.3
- phpstan/phpstan-strict-rules: ^2.1
- rector/rector: ^2.8
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A highly opinionated Laravel package to sync environment variables between different .env files and view differences between them. Ensures all your .env files are consistent, clean, and strictly follow best practices for key/value formatting.
Features
- Strict .env key rules: Only allows keys that are upper snake case, starting with an uppercase letter and containing only uppercase letters, numbers, or underscores (minimum 2 characters).
- No leading/trailing spaces: No line in any
.envfile may have leading or trailing spaces. Values must not have leading or trailing spaces. - Only recognised lines: Every line of every
.env*file must be blank, a comment (#) orKEY=VALUE. Any other line stops the command before a single file is changed. - Identical structure: The synced
.envfiles will have the exact same structure, order, comments, and blank lines as.env.example, differing only in values where present, plus each file's own keep block at the end. - Optional keys: A key that
.env.examplecomments out (# APP_MAINTENANCE_STORE=database) may be set in any other file; the sync keeps that file's value in place of the comment. - File-specific keys: Lines below
# sync-env:keepin a target file are left as they are, for keys only that file needs (such asAPP_PORTfor Docker Compose on a dev machine). - Sync .env files: Synchronize keys from
.env.exampleto all other.env*files, preserving existing values and creating backups. Keys a sync removes are always listed. - Show diffs: View differences between
.env.exampleand other.envfiles, including options to show all keys or include backup files. - Backup management: Automatically create backups before syncing, and remove old backups with options.
Key Format Rules
- Keys must be in UPPER_SNAKE_CASE.
- Keys must start with an uppercase letter (
A-Z). - Keys must be at least 2 characters long.
- Keys may only contain uppercase letters (
A-Z), numbers (0-9), and underscores (_). - No leading or trailing spaces are allowed in any line.
- Values must not have leading or trailing spaces.
Examples
Valid keys:
APP_NAME
DB_CONNECTION
FOO_BAR_123
Invalid keys:
app_name # not uppercase
A # single character not allowed
_DB_CONNECTION # cannot start with underscore
APP_NAME # leading space
APP-NAME # dash not allowed
APP NAME # space not allowed
APP@NAME # special char not allowed
Invalid values:
APP_NAME= MyApp # leading space in value
APP_NAME=MyApp # trailing space in value
Requirements
- PHP
^8.5 - Laravel
^13.35
Installation
composer require mahbubhelal/sync-env
Usage
1. Sync .env files
Synchronize .env.example to all other .env* files:
php artisan sync-env:example-to-envs
Options:
--no-backup(-N): Do not create a backup of the target.envfile before syncing.--remove-backups(-r): Remove previously created backup files before syncing.--dry-run(-d): List the keys each file would gain or lose without writing anything.--only=: Only sync specific env files (comma-separated, e.g.,--only=.env,.env.staging). A missing.envis only created when it is selected.--exclude=: Do not sync specific env files (comma-separated, e.g.,--exclude=.env.testing).-v(verbose): Show detailed warnings about comment differences and key position differences.
The command fails, changing no file, when --only and --exclude leave no file to sync.
Optional keys
A commented-out key in .env.example is optional: a target file may set it or leave it out.
# .env.example
APP_MAINTENANCE_DRIVER=file
# APP_MAINTENANCE_STORE=database
# .env.production after a sync: its own value replaces the comment
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=redis
Files that do not set the key get the comment. A comment counts as a key when the text after # (and any spaces) is KEY=VALUE with a valid key. If .env.example also sets the key on a line of its own, the comment stays a comment. If it comments the same key out more than once, only the first comment is replaced.
Keeping file-specific keys
Everything from a # sync-env:keep line to the end of a target file is kept as it is, after one blank line:
# .env
APP_NAME=MyApp
...
# sync-env:keep
APP_PORT=8081
Keys above the marker that .env.example does not have are removed, so keys renamed or dropped in .env.example still disappear from the other files. The command fails, changing no file, when:
.env.exampleitself contains the marker, or- a key below the marker is also in
.env.example, set or commented out.
2. Show differences between .env files
Display differences between .env.example and other .env files:
php artisan sync-env:show-diffs
Options:
--all(-a): Show all keys, including identical ones.--include-backup(-b): Include backup files in the diff view.--only=: Only show specific env files (comma-separated, e.g.,--only=.env,.env.staging).--exclude=: Exclude specific env files (comma-separated, e.g.,--exclude=.env.testing).
Two labels mark what the sync keeps:
(optional)in the.env.examplecolumn: the key is commented out there. The row is shown when a file sets the key, or with--all.(kept)after a file's value: the key sits below that file's# sync-env:keepline.
Rows marked - are keys .env.example doesn't have. Their values without (kept) are removed by the next sync.
Note: At least 2 env files are required. If --only or --exclude results in fewer than 2 files, .env.example is automatically included, and the command says so.
Example Workflow
- Update your
.env.examplefile with new keys or changes, following the strict key/value rules above. - Run the sync command to propagate changes to all
.envfiles:php artisan sync-env:example-to-envs
- Use the show-diffs command to review differences:
php artisan sync-env:show-diffs
Development
The package ships with a Docker-based dev environment. Common commands:
./dc buildup # build and start the containers ./dc composer install # install dependencies ./ci # every check: rector, pint, phpstan, type and line coverage (both 100%) ./ci all # apply rector and pint fixes, then run phpstan, type coverage and tests ./ci pest --filter=Name # run tests; also ./ci rector|pint|phpstan|types|coverage
License
The MIT License (MIT). See LICENSE.
Author: Md Mahbub Helal (mdhelal00@gmail.com)