imanghafoori/php-search-replace
PHP Search Replace is a command-line tool for finding and replacing strings across files in a project. Use it to perform bulk edits, refactor code, or update repetitive text safely from the terminal, making large-scale file changes faster and easier.
Architecture fit. imanghafoori/php-search-replace is a framework-agnostic PHP source-rewriting library: it matches structural patterns in PHP token streams and emits replacements. Architecturally this belongs in build-time / developer tooling, never in the production dependency graph. It should live in require-dev of an internal tooling repo or a dedicated tools/codemods package — not in an application's composer.json. Its natural role is a narrower, scriptable alternative to Rector for repetitive mechanical refactors: renaming a method across 400 files, swapping a facade call for a service call, migrating a signature, or transforming a boilerplate block. It has no runtime, request-path, or service-provider surface, which keeps blast radius low — provided it is never wired into an auto-commit pipeline.
Integration feasibility. Technically trivial: a Composer install plus a small driver script that walks directories and invokes the replacer per file. There is no framework coupling, no config publishing, no container binding. The real feasibility question is not "can we install it" but "can we trust it to not corrupt source." Feasibility is high for a read-only, diff-producing pilot; it is unproven for unattended application. Verification work is concentrated in three areas: (1) modern-syntax coverage (enums, readonly, promoted constructor properties, first-class callables, attributes, arrow functions, match) — token-based matchers commonly lag AST-based ones on new grammar; (2) whitespace/formatting preservation, since destructive rewrites often reformat surrounding code and produce noisy diffs; (3) performance and memory on large monorepos.
Technical risk. Low-to-moderate, conditional on guardrails. The package is single-maintainer, 32 stars, 0 Packagist dependents, and scored 19.8 overall — meaning there is effectively no ecosystem validation and no third party to learn from. You will be the first meaningful integrator. Key hazards: destructive file writes without a diff/dry-run mode, non-idempotent replacements, silent no-op matches (pattern looks right, matches nothing, refactor appears complete), over-matching inside strings, comments, or unrelated namespaces, and mid-run crashes leaving a partially migrated tree. Mitigations are cheap and standard: run on a clean branch, commit before applying, wrap with git diff --exit-code checks, and require human PR review on every generated change.
Key questions.
token_get_all or a full AST (nikic/php-parser), and how does it behave on PHP 8.3/8.4 syntax?Stack fit. Position it in the engineering-productivity layer: a sibling to PHPStan/Pint/Rector in the "code health" toolchain, invoked locally or in a manual CI job. It fits a Laravel/PHP shop that already has frequent mechanical migrations (Laravel major upgrades, PSR-4 namespace moves, internal SDK renames) and where writing a full Rector rule is disproportionate to the task. It does not fit alongside PHPStan as an automated gate, because it mutates rather than reports.
Migration path. Adopt in stages. (1) Scratch branch PoC on one low-risk module with a single narrow pattern. (2) Side-by-side comparison against Rector for the same transformation — if Rector already covers it, prefer Rector for its ecosystem and maintainer depth. (3) If adopted, wrap the library in a thin internal Codemod entrypoint that defaults to dry-run, emits unified diffs, and refuses to write when the working tree is dirty. (4) Pin the fork/exact version and vendor it into the tooling repo. Never depend on a floating dev-master.
Compatibility. Pin the exact version in composer.lock; run the tool inside a fixed PHP container image so local and CI produce byte-identical output. Validate against the oldest and newest PHP versions in the support matrix. Because the library reads and rewrites source, its PHP version compatibility must be at least as broad as the widest PHP version present in the codebase it will touch.
Sequencing. Tooling repo and wrapper first → dry-run-only CI job (check mode, always exit 0) for one sprint → enable write mode behind a manual label for one team → generalize. Do not sequence this before the codebase has PHPStan + Pint + a formatter gate; those catch what the replacer damages.
Maintenance. The dominant cost is not the library, it is the patterns. Each codemod is code with a lifecycle: authored, tested, run once, then obsolete. Recommend a tools/codemods repo with one directory per migration and a fixture-based test (input.php → expected.php) so patterns are validated before touching real source. Budget roughly 2–5 engineering days per year for PHP-version token drift, and assume you may need to fork — MIT makes that cheap. Watch upstream release cadence; a single-maintainer package with 0 dependents has no downstream pressure to stay current.
Support. No vendor, no SLA, GitHub issues only. Internal ownership must be explicit — name a "codemod maintainer" (usually a senior backend engineer, part-time). Do not let it become unowned shared tooling.
Scaling. Fine for repo-wide batch runs where the workload is one-shot and human-reviewed. For monorepos, shard by top-level directory to parallelize and to bound memory. The scaling failure mode is not throughput, it is diff volume — a single pattern applied across thousands of files produces an unreviewable PR; chunk migrations by module and land them incrementally.
Failure modes.
Ramp-up. Low for a mid/senior PHP engineer — the pattern DSL is learnable in a day with a cookbook of 5–10 worked examples. Non-trivial for everyone else, which is appropriate: restrict write access to codemods to a small group, keep dry-run available to all. Plan a 30-minute internal walkthrough plus a written "how to write and test a codemod" doc as the onboarding artifact.
How can I help you explore Laravel packages today?