Download the PHP package phptramp/phptramp without Composer

phptramp

Detect tramp data in PHP codebases: parameters that get passed through chains of methods that never use them — "this parameter was passed through 4 classes / 5 methods before being used."

What it does

The origin is hop 1, so a 3-hop chain runs origin → hop 2 → hop 3 → terminal; the summary counts the origin. Add --explain to see, per edge, how each call was resolved.

A hop is a method that receives a parameter and purely forwards it — never reads a property, never calls a method on it, never uses it in an expression. Long hop chains are the "tramp data" smell: every method in the middle is coupled to a value it has no business knowing about. The fix is usually a parameter object, a context object, or dependency injection at the terminal — this tool tells you where.

Construction and delegation don't count: a constructor forwarding to parent::__construct() (or any parent:: call) is the same object handling its own value, so that node scores neither a hop nor a class and is marked (parent) in the chain.

Diff-aware CI mode

The flagship feature is diff-aware CI mode: run it on a pull request and it reports "your edit made this chain longer", marking exactly which hops are yours. --changed-only restricts findings to chains that intersect a diff — a hop matches iff its declaration line or its forwarding call-site line was touched — and each matching hop's location line grows a *YOURS* annotation:

The →N after a hop's file:line is the forwarding call-site line — the line inside that method where the parameter is forwarded on. Terminal hops have no forwarding call, so they show only file:line. When a method forwards the same parameter to the same callee via multiple call sites, each produces its own finding distinguished by this →N value.

--git-base <ref> (default origin/main) supplies the diff via git diff --unified=0 <ref>...HEAD (three-dot, merge-base semantics); --diff <path|-> reads a unified diff from a file, or from stdin with -, instead — either always implies --changed-only. See docs/ci.md for GitHub Actions and GitLab recipes.

Installation

composer tramp

Add a script to your project's composer.json to invoke it the short way:

This repository gates itself with exactly this script — see its own phptramp.dist.json.

CLI

Exit codes: 0 no finding at error severity, 1 at least one finding at/over --limit, 2 tool error — so it drops straight into any CI pipeline.

Configuration

phptramp reads phptramp.json (falling back to phptramp.dist.json) from the current working directory; CLI flags always win. All keys, the index cache, and performance numbers are documented in docs/configuration.md.

Output formats

--format selects the renderer; all seven are implemented and each has an exact-string unit test.

pretty is the default on a TTY; pipes and CI fall back to text automatically. --color=always|auto|never overrides (NO_COLOR is honored in auto mode).

In a --changed-only run, each json chain entry additionally carries a "changed": true|false field marking whether that hop intersects the diff; a normal full run omits the field entirely rather than sending it as always-false noise.

Suppression

Mark a specific false positive as intentional instead of raising --limit project-wide:

• #[TrampIgnore] on a class, method, function, or parameter. Matching is by the attribute name's short name, so an analyzed codebase never has to require or autoload phptramp's own PhpTramp\Ignore\TrampIgnore class to use it.
• // phptramp-ignore as a real PHP comment (a marker inside a string literal does not count) on a hop's declaration line, the line directly above it, or a forwarding call-site line.

Either drops the entire chain passing through that hop, not just the one parameter reaching the flagged declaration.

--warn-limit

--warn-limit <n> adds a second, lower threshold below --limit. Chains whose hop count falls in [warn-limit, limit) render at severity: "warning" (WARNING in text, ::warning in the GitHub format, "level": "warning" in SARIF, …) but never fail the run — only chains at or over --limit set exit code 1. Useful for tightening a hop budget gradually: warn today, promote to a hard failure once the codebase is clean.

0 disables the warn tier entirely (no warnings emitted); --limit 0 likewise disables the fail tier, leaving only warnings. --min-classes <n> is a complementary filter: it suppresses any chain traversing fewer than n distinct classes regardless of severity, so you can scope a noisy warn tier to genuinely wide chains.

Baseline

Adopting phptramp on a codebase with existing tramp data? --baseline snapshots today's findings so CI only gates new chains, with refactor-stable fingerprints that survive renames and moved lines — and --fail-on-stale nudges you to prune entries as you fix them. The full workflow is in docs/baseline.md.

IDE integration

PhpStorm (and any IDE with external-tool support) can run phptramp per file via --file; a documented External Tool + File Watcher recipe is in docs/phpstorm.md. --format=checkstyle and --format=sarif cover CI annotation ecosystems, including GitHub Code Scanning.

Non-goals

• No auto-fix. Fixing tramp data means refactoring (parameter objects, DI rewiring), which is not mechanically safe. phptramp reports; you decide.
• No second production dependency. nikic/php-parser is the only one, deliberately.

Contributing

Contributions are welcome — see the contributing guide for the workflow and the CI gates, and the code of conduct. Bugs are best reported with the bug report form.

License

MIT