Php Search Replace Laravel Package

Product Decisions This Supports

• Build vs. buy for internal codemods. Instead of writing bespoke regex/sed scripts or a one-off token parser every time a rename is needed, this package offers a reusable primitive for "smart" (syntax-aware) search-and-replace against PHP source. That is a build-vs-adopt call a PM can frame as: small dependency, dev-only, replaces ad-hoc scripts we keep rewriting.
• Framework and dependency upgrade roadmap. Every Laravel/PHP major bump implies mechanical edits: renamed helpers (str_random() → Str::random()), moved namespaces, deprecated facade methods, config key changes. A tool like this turns those into a scripted, reviewable migration step rather than a multi-day manual sweep — directly affecting the "can we do the upgrade this quarter?" estimate.
• Shipping upgrade tooling to our own consumers. If we maintain an internal package or SDK, we can ship a codemod script alongside a breaking release so downstream teams migrate themselves. This shifts support load off the platform team and improves adoption of new versions.
• Deprecation and tech-debt burn-down. Bulk removal of deprecated API usage, consolidation of duplicated helper classes, or enforcing a house convention across a monorepo (rename a base class, replace a custom macro with a first-party call). Useful input to "how much of our debt is mechanically fixable vs. requires design work?"
• Scope decisions for a refactor epic. Running a search pass first gives an inventory: N call sites across M files. That data sizes the epic and decides whether it's a codemod (hours) or a design change (sprint).
• Tooling investment tier. Signals whether the team needs a full Rector/phpstan-grade refactoring pipeline or whether a lightweight scripted utility is proportionate to codebase size.

When to Consider This Package

Consider it when:

• The codebase is PHP-only and you own the source (application code, not vendor/).
• The change is mechanical and deterministic: identifier renames, namespace moves, method-signature swaps, constant replacement, removing a deprecated call pattern.
• You want something lighter than authoring Rector rules — no rule classes, no configuration DSL, just a script you check into tools/ or migrations/ and run on a branch.
• It's a dev dependency only (composer require-dev), invoked in one-off scripts or CI hygiene jobs, with zero runtime footprint.
• You can validate the output: a decent test suite, static analysis, and a human-reviewed diff. The value is speed of the diff, not correctness assurance.
• MIT licensing and no vendor relationship needed.

Look elsewhere when:

• Maintenance risk matters. 32 stars, 0 dependents, a single maintainer, and a release date that appears future-dated (2026-10-08) are all yellow flags for anything load-bearing. Verify commit cadence, test coverage, supported PHP versions, and open-issue responsiveness before betting a migration on it.
• You need type-aware or semantic refactoring — resolving what a symbol actually refers to, following inheritance, handling dynamic dispatch. That's Rector, PHPStan, or an IDE (PhpStorm) refactor.
• You only need style/formatting normalization — PHP-CS-Fixer or Pint is the right tool.
• The codebase is polyglot or replacements reach into Blade templates, JS, YAML config, or serialized class names in the database — token-level PHP rewriting will silently miss these, which is the exact failure mode that makes the change dangerous.
• Replacements depend on strings, reflection, or container bindings that reference class names textually — those need a separate, explicit inventory.
• You require vendor support, an SLA, or a security review of the supply chain.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed developer tool that automates the mechanical part of framework and dependency upgrades. The business case is cycle time: rename-and-replace work that currently consumes days of senior engineer attention becomes a scripted job that runs in minutes and produces a reviewable diff. It carries no production runtime cost — it's a dev-only dependency used in migration scripts — so the risk profile is low and reversible. The caveat worth stating plainly: it's a single-maintainer, low-adoption project, so we should treat it as a tactical utility for one or two migrations rather than strategic infrastructure, and keep the scripts in-repo so we're never locked in.

To engineering: Treat this as a codemod helper, not a compiler. Proposed adoption path: (1) spike it against one real, scoped change — a helper rename or namespace move in a single package; (2) run it on a branch, diff the output, and confirm with the existing test suite plus static analysis; (3) measure false positives and missed call sites, especially dynamic references (strings, config, reflection); (4) if the diff is clean, promote the script into a tools/codemods/ directory with a short README and a "run on a branch, review the diff, require green CI" rule. Keep the invocation pinned and dev-only, exclude vendor/, and set an explicit escalation rule: the moment we need type resolution, inheritance awareness, or multi-file semantic edits, we switch to Rector rather than growing this into a homegrown refactoring engine. Budget roughly a day for the spike; the decision gate is whether one real migration completes with a diff a reviewer can trust.