Download the PHP package phpcpd-next/phpcpd without Composer

phpcpd-next

Token-based copy/paste detection for PHP 8.5+ — a maintained successor to phpcpd, with reorder-tolerant (Type-3) detection.

A maintained, dependency-free successor to the archived sebastianbergmann/phpcpd. It finds duplicated code — and, unlike most copy/paste detectors, it ships three complementary detection engines so it can see exact copies, reordered clones, and gapped near-misses.

Drop-in replacement: the command is still phpcpd. Out of the box it runs Rabin-Karp + TokenBag (exact and reordered duplication); the classic Rabin-Karp-only behaviour is one flag (--rk) away. The deeper research engines are opt-in.

Features at a glance

• Three token-based engines — Rabin-Karp (exact) and TokenBag (reordered) run by default; the suffix tree (gapped Type-3) is an opt-in research engine.
• Orphan detection (--orphans) — find unreferenced classes, interfaces, traits, enums, and functions, with two confidence tiers and framework entry-point awareness.
• Actionable console output — every clone comes with a context-aware refactoring hint, plus a run summary (duplicated-line percentage, average and largest clone size).
• Inconsistent-clone reporting — with --algorithm=suffixtree, diverged near-misses are flagged [inconsistent] (the bug-prone kind: one copy patched, its sibling not).
• Four output formats — human-readable console, PMD-CPD XML, JSON, and SARIF 2.1.0.
• CI-ready — meaningful exit codes, result caching, and a per-file incremental index.
• Framework presets — --preset=laravel (and an extensible preset format).
• Headless API + PHPUnit integration — embed detection in tests or tools, no shelling out.
• PHP 8.5+, zero runtime dependencies, deterministic — same input, same result, every run.

Why another clone detector?

The common wisdom is that phpcpd only finds Type-1/2 (exact / renamed) clones. That was only ever true of its default engine. phpcpd-next exposes and extends the full picture:

The two default engines run together on every phpcpd <dir> invocation. The Type-3-gapped and Type-2 capabilities are research-grade and opt-in (see Advanced engines).

The suffix-tree engine additionally flags inconsistent clones — near-miss copies that have diverged — which is where duplication tends to hide bugs (one copy patched, its sibling not).

Requirements

• PHP 8.5+
• ext-dom, ext-mbstring

Zero Composer dependencies. Nothing from the PHPUnit/sebastian release train at runtime.

Installation

Install as a dev dependency from Packagist:

This installs the phpcpd binary to vendor/bin/phpcpd:

Or run it without adding it to your project, via Composer's global bin or a one-off:

From source:

Requires PHP 8.5+ with ext-dom and ext-mbstring. Zero runtime dependencies — nothing from the PHPUnit/sebastian release train is pulled in.

Quick start

phpcpd-next exits with status 1 when clones are found (or on error) and 0 when none are — so it works as a CI gate out of the box.

What a run looks like

Each clone is followed by a context-aware refactoring hint — the suggestion adapts to the clone (test scaffolding, a large block, a diverged near-miss, or a plain extract). The closing summary reports the duplicated-line percentage and the average/largest clone size. Add --verbose to print the duplicated source itself.

Detection engines

Default: Rabin-Karp + TokenBag

Every phpcpd <dir> run executes two engines and merges their results:

• Rabin-Karp — exact contiguous duplication via a rolling hash. Fast; the classic phpcpd behaviour for Type-1 clones.
• TokenBag — order-invariant overlap (a SourcererCC-style token bag + inverted index). Catches clones where statements were reordered within a function — which contiguous matching cannot.

They are complementary: Rabin-Karp is precise about structure; the token bag tolerates shuffling. Pass --rk to run Rabin-Karp alone (faster, no reorder detection).

Advanced engines / research

These are opt-in via the (hidden) --algorithm flag and its tuning knobs. They are research-grade — powerful on the right corpus, but with higher false-positive rates on real-world code, which is why they are not in the default set or in --help.

• --algorithm=suffixtree — approximate matching with a configurable edit budget (--edit-distance, default 5). Detects gapped (Type-3) clones where statements were inserted, deleted, or changed, and marks diverged copies as [inconsistent]. Type-aware: a changed control keyword (if→while) costs more of the edit budget than a renamed identifier. Tune the exact-match prefix with --head-equality (default 10).
• --algorithm=tokenbag — run the token bag alone (rather than merged with Rabin-Karp). Tune the overlap threshold with --min-similarity (default 0.7).
• --algorithm=rabin-karp — explicit single-engine Rabin-Karp (equivalent to --rk).
• --fuzzy — rename-insensitive (Type-2) matching: identifiers and literals are abstracted to type classes. --type-anchored is the same but preserves type keywords.

Orphan detection (dead code)

Clones are duplicated code; orphans are unreachable code — a class, interface, trait, enum, or global function that nothing references. Same token engine, no parser, no AST, no runtime dependency.

Two modes:

• Default run — orphans ride along with the clone scan as an advisory: they're reported, but only clones set the exit code. (Safe for framework-heavy projects where dynamic dispatch causes false positives — see the Laravel note below.)
• --orphans — orphans only, and they gate CI: a definite orphan makes the run exit non-zero, exactly like a clone.

Each finding is explained, not just listed:

• whole file is unwired — every symbol in that file is an orphan, so the whole file is dead (phpunused's "unreferenced file", at symbol granularity).
• looks like a superseded copy of X — the orphan's body duplicates a live symbol, so it's almost certainly the stale copy a refactor replaced and forgot to delete. This reuses the clone engine — the orphan × clone synergy that a pure dead-code linter can't offer.

Two confidence tiers, so the tool never nags you into deleting live code:

What it won't false-alarm on — framework entry points are reachable even when unreferenced:

• Classes wired via attributes: #[Route], #[AsCommand], #[AsEventListener], #[AsMessageHandler], #[Entity], #[Attribute], and more.
• *Test classes (discovered by the test runner, not by a reference).
• Anything marked @api, @psalm-api, @phpstan-api, @phpcpd-keep, or @phpcpd-ignore-orphan.

Scope, honestly. Orphan detection stops at the type/function level — the "unreferenced file" case. Method- and property-level dead code needs whole-program type inference (which class does $this->handle() resolve to under inheritance and a DI container?); that is PHPStan + Psalm's job, and this token-based tool deliberately does not guess at it. What it does do — decide whether a named type or function is ever mentioned at all — it does safely: reference detection is generous by design, so it prefers to stay silent over flagging something that is used. Point it at a whole project (including bin/, entry scripts, and config) so legitimate roots are seen as referenced.

Laravel and other convention-driven frameworks. Treat orphan output as review candidates, not a delete list. Laravel reaches many classes with no by-name reference, and they fall into three buckets: [Controller::class, 'method'] routes, $listen/$subscribe arrays and app(Foo::class) all use ::class, which counts as a real reference; string-based references (string route actions, class names in config/, container bindings) are demoted to possible — as long as you scan those files too (routes/, config/); but convention/auto-discovery (policies, Livewire/Filament components, commands loaded via load(), model observers) leaves classes with no textual mention at all, and those will false-positive. This is exactly why orphans are advisory in the default run — scan the whole app, lean on the possible tier, and reach for --orphans (the gating mode) on code you control.

Embed it the same way as clone detection:

Output formats

The console report is human-readable and always printed; add --verbose to print the duplicated source of each clone. Machine-readable reports are written to a file in parallel:

You can request several at once. SARIF maps inconsistent clones to warning and exact clones to note, so the bug-bearing duplication surfaces at a higher severity.

GitHub Code Scanning

Clones then appear as annotations in the PR and in the repository's Security tab. (Swap in --algorithm=suffixtree if you also want gapped/inconsistent clones surfaced.)

Options

The full set shown by phpcpd --help:

Advanced / research flags

Parsed but hidden from --help — research-grade, see Advanced engines:

Framework presets

A preset is a named bundle of sensible defaults — scan paths, file suffixes, and exclude patterns — for a given framework. It is pure configuration: no runtime dependency, no change to how detection works, so it stays faithful to the zero-dependency, deterministic core. Presets exist because every framework has predictable noise (generated caches, scaffolded CRUD, migration boilerplate) that buries real findings; a preset encodes that knowledge once.

Explicit flags always win: a preset seeds the defaults, then --exclude and --suffix append to it and --min-lines / --min-tokens override it. Passing a directory overrides the preset's default paths (its excludes still apply):

Presets are declared in one place (src/Presets.php); adding a framework is a single Preset entry that the CLI, --help, and the headless API all pick up.

Laravel via Artisan (optional)

There is no Laravel runtime dependency in phpcpd-next, and there does not need to be — --preset=laravel is the integration. If you want php artisan ergonomics, a few lines in your app wire the headless API (below) into a command; no extra package required:

Embedding phpcpd-next (headless mode)

Tools that want clone detection in-process — a PHPUnit assertion, an Artisan command, a custom CI script — call the headless API instead of shelling out to the binary. It finds files, runs the same engine the CLI uses, and returns the raw CodeCloneMap; there is no banner, no argv parsing, and no file I/O, so it is safe to call repeatedly in one process.

PHPUnit integration

Make duplication a regression test: a clone introduced in a pull request turns the build red, with the offending locations printed in the failure message. Drop in the shipped trait:

On failure:

The trait and the underlying DuplicationConstraint live in integration/phpunit/, autoloaded under LucianoPereira\PhpcpdNext\PHPUnit\ once phpcpd-next is a require-dev of your project. phpcpd-next dogfoods it: its own tests/SelfDryTest.php uses this exact trait to keep src/ duplication-free across all three engines.

Incremental caching (CI)

--cache stores the run's results keyed by a fingerprint of the configuration and a manifest of every scanned file's hash. On a re-run with the same files and config, detection is skipped entirely and the cached result is replayed (the run prints (cache hit)). Any changed, added, or removed file is a miss and triggers a full re-scan. Different algorithm/threshold combinations get separate cache entries, so they never collide.

Mount the cache directory with actions/cache to carry it between CI runs:

Per-file incremental index (--incremental)

--cache is all-or-nothing: a single changed file invalidates the whole run. --incremental (Rabin–Karp only) is finer-grained — it persists each file's tokenization keyed by a content hash, and on a re-run re-tokenizes only the files that changed, replaying the rest straight from the index. The run prints what it did, e.g. (incremental index: 412 reused, 3 scanned).

The result is identical to a full scan — only the work differs — so it stays correct as files come and go between runs. Use it on large codebases where most files are untouched between CI runs; mount the same .phpcpd-cache directory with actions/cache as above. (Requested with another algorithm, the flag is ignored and the run falls back to the coarse --cache.)

Lineage and license

phpcpd-next is a fork of sebastianbergmann/phpcpd, created by Sebastian Bergmann and archived in

2023. The original copyright is retained throughout; this fork is maintained by Luciano Federico Pereira. Licensed under BSD-3-Clause — see LICENSE.

The diff-by-diff story of the modernisation and the new detection capabilities lives in paper. Contributions are welcome under the CONTRIBUTING.md.