Proteus Laravel Package

Product Decisions This Supports

• Setup and onboarding wizards. This is the strongest PM-level use case: a first-run experience or installation command that writes app.php, database.php, or a package's own config file on the customer's behalf. A "one command to configure" flow measurably improves activation and cuts support tickets caused by hand-edited PHP arrays and stray commas.
• Build vs. buy: buy. The value here is not "writing a config file" — it's safely editing a PHP source file (AST-level) while preserving formatting, comments, and env() calls. Reproducing that with nikic/php-parser plus a printer is weeks of engineering for a small, MIT-licensed dependency. Building in-house is only justified if you already own a PHP-AST editor.
• Feature/roadmap candidates it unlocks:
  • Installer recipes for your own package ("register our service provider in config/app.php" as a generated step, not a copy-paste doc).
  • Admin-facing settings pages that write to real config files, with guard() protecting app.key, mail credentials, and other sensitive namespaces.
  • Multi-tenant or per-environment provisioning: generate tenant-specific config files at tenant creation rather than templating strings by hand.
  • Automated config upgrades during major-version migrations (rewrite a deprecated key across customer files programmatically).
• Where it does not decide anything: runtime settings for a running app. Laravel caches configuration, so file writes are a deploy/provisioning-time action, not a live toggle mechanism. Treat this as a provisioning and automation dependency, not a feature-flag system.

When to Consider This Package

Adopt when:

• Your target config files are Laravel-style PHP arrays and you need edits to be human-reviewable in a diff — preserved formatting and comments are the core differentiator versus regex or var_export.
• The write happens in controlled, non-concurrent contexts: install commands, CI provisioning, tenant creation, migration scripts, local dev tooling.
• You need env() calls left intact by default (the v2 default), with preview/previewMany to show a dry run and guard()/preserve() to enforce policy on protected keys.
• You want a small, MIT-licensed, ecosystem-native dependency that tracks Laravel releases (v4.2.x supports Laravel 13) and can be pinned.

Look elsewhere or add mitigation when:

• Writing config for a live, cached production app. Nothing here addresses Laravel's config cache; you'd be writing files nothing reads until the next deploy.
• Secrets management. This is not a secret store or a vault bridge. Prefer keeping credentials in environment variables and preserving env(); use guard() aggressively if you expose any write path to users.
• Concurrency and safety guarantees. There is no documented atomic-write, file-locking, or rollback story. If two processes can write the same file, or a bad write can take down a site, put your own backup/validate/commit layer around it.
• Non-PHP config (YAML, JSON, .env files) or non-Laravel frameworks — it is explicitly scoped to Laravel-style PHP arrays.
• Ecosystem support risk tolerance. 18 stars, zero dependents, a single-maintainer project: a defensible choice for a bounded internal tool, a weak one for a load-bearing, customer-facing critical path without the ability to fork. Budget a small spike to validate against your exact target files and pin the version.

Validation gate before commitment: run a one-day spike on your three most-edited real config files; confirm round-trip fidelity (comments, ordering, function calls, ::class constants) and that guard()/preserve() behave as expected. If the round-trip diff is clean, risk is low.

How to Pitch It (Stakeholders)

Executives: A small, MIT-licensed library that lets our product safely edit Laravel configuration files automatically — the setup steps customers currently do by hand, badly. It converts our most error-prone onboarding instructions into a single command, which shortens time-to-first-value and reduces the configuration tickets our support team absorbs. Cost is negligible, it's a dependency not a platform bet, and it's constrained by design: credentials stay in environment variables and cannot be overwritten through our write paths. Engineering effort is measured in a spike plus one feature, not a project.

Engineering: It's a thin, focused AST layer over nikic/php-parser with a facade (write, writeMany, edit()->set/merge/replace/remove) plus preview for dry runs. Defaults are sensible for our threat model: env() calls are preserved, and guard() throws on protected mutations. Two things we own explicitly — where we call it (install/provisioning/migrations, never mid-request on a cached config) and how we call it (validate + snapshot + write, behind an admin permission, with preview surfaced as a diff for review). We pin the version, add contract tests against our real config files, and keep the call sites isolated behind one internal service so a fork or replacement is a small blast radius.