Filament Edit Env Laravel Package

Getting Started

The package adds an "Edit Env" page to a Filament panel so trusted operators can change .env values without SSH. v3.0.0 is a major release and the changelog link carries no detail — assume it targets a newer Filament major (v4) and treat the upgrade as a compatibility migration until you've verified the constraints.

Minimal path:

composer require joaopaulolndev/filament-edit-env

php artisan vendor:publish --tag="filament-edit-env-config"
# publish migrations/views too if you want backup history or a customised UI

Register the plugin on the panel (not globally) in your PanelProvider:

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->plugin(FilamentEditEnvPlugin::make());
}

Then check, in order:

1. composer.json constraints — confirm the installed Filament version matches what v3 requires; if you're still on Filament v3, stay pinned to ^2.0 and don't upgrade the constraint by accident.
2. The published config file — this is where access control, editable-key limits, backup behaviour and cache handling live. Read it before you read the page code.
3. Authorization — the page should be gated to a single role (e.g. super_admin), not merely "logged into the panel".

First real use case: a self-hosted or staging app where changing a mail driver, third-party API key or feature flag currently means a deploy. Local dev is a poor test bed — the panel works everywhere, but the failure modes (read-only .env, config cache, platform-injected env vars) only show up on real infrastructure.

Implementation Patterns

Scope the plugin to non-production panels. The cleanest pattern is a separate panel provider for ops tooling, or a conditional registration:

->plugin(
    FilamentEditEnvPlugin::make()
        ->visible(fn () => auth()->user()?->hasRole('super_admin'))
)

If the plugin exposes no visible()/authorization hook in v3, wrap it in a Gate::define('edit-env', ...) check and register the plugin only when Gate::allows() at boot — or subclass the page and override canAccess().

Allow-list keys, don't expose the file. The single most valuable config change is restricting which keys are editable. APP_KEY, APP_ENV, DB_* and anything consumed by the deploy pipeline should be read-only or absent. Editing APP_KEY in place silently invalidates encrypted columns, sessions and signed URLs.

Make cache-clearing part of the save. Config is loaded once per request; an env edit does nothing for the running process. If the package offers a post-save cache clear, enable it; otherwise add a small action/observer that runs php artisan config:clear (or config:cache) and, for Octane/queue workers, signals a restart. In production a common workflow is: edit → clear cache → restart workers → verify.

Backups as a safety net, not a strategy. If the release keeps the backup/restore feature, point the backup disk at local (never public), keep a retention/prune job, and store a timestamped copy in your normal backup pipeline too. .env backups are plaintext secrets.

Audit around the package, not in it. Most env editors log nothing. Wrap saves with an activity()/audit entry recording who changed which keys — never the values. This is also the only way to answer "why did mail stop working at 14:03".

Test the boundary. In Pest/PHPUnit: assert a non-admin gets 403 on the page, assert an admin sees it, and use a temporary env file (Storage::fake or a fixture path) so tests never touch the real .env.

Gotchas and Tips

• v3 upgrade checklist. No migration notes were provided, so verify manually: Filament v4 moved form definitions from Filament\Forms\Form to Filament\Schemas\Schema and relocated actions into Filament\Actions. If you've published and customised the page/view, re-publish and diff. Re-run migrations if the backup table changed, and re-test the gate — a silently accessible env editor is the worst possible upgrade outcome.
• Platform-managed environments are a no-op. Vapor, Heroku, Laravel Cloud and most container setups inject env vars at runtime; the file is ephemeral or read-only. The package will appear to save and then be reverted on the next deploy. Know which of your environments is file-backed before shipping this to operators.
• Permissions. The PHP-FPM user needs write access to .env — often it's 640 owned by the deploy user. Symptom is a silent failure or a generic "could not save" error; check storage/logs and the file owner first.
• Parsing edge cases. Values containing #, spaces, quotes, = or newlines (JSON blobs, PEM certificates, DSNs) are where dotenv writers mangle output. Keep such secrets in files or a secret manager, not in the editor. After any bulk edit, diff the file against a backup before clearing the config cache.
• Stale config after save. Because the edit doesn't affect the current request, operators frequently report "I changed it and nothing happened". Put the cache-clear + worker restart instruction directly in the page's helper text or a success notification.
• Debug mode. Don't let this page be reachable while APP_DEBUG=true in an environment with real users — stack traces on a failed save can leak env contents.
• Extension points worth knowing: published views for UI tweaks, subclassing the page class for custom validation (e.g. rejecting values with \n), the config file for key filtering, and the backup restore flow for rollback. Prefer config/subclass over editing vendor files so the next major bump stays cheap.
• Pin deliberately. If you can't test Filament 4 this sprint, keep "joaopaulolndev/filament-edit-env": "^2.0" and schedule the v3 bump with the framework upgrade, not before it.