Download the PHP package infocyph/phpprobe without Composer

PHPProbe

Standalone PHP checker for syntax validation, duplicate-code detection, public API snapshot checks and comment policy checks.

PHPProbe is the checker runtime. It can be used directly as phpprobe, required by tool-combiner packages such as PHPForge, or called from PHP code through the public gateway classes.

Requirements

• PHP >=8.2
• nikic/php-parser >=5.0 <6.0
• phpstan/phpdoc-parser ^2.3

Install it as a Composer tool dependency:

The package ships a Composer binary:

Commands

Unknown commands print the top-level usage and exit 0. There is no separate --version command. For checker subcommands (syntax, duplicates, api, comments, check), unknown options fail with exit 2.

Onboarding (5 Minutes)

Use this flow for a fresh project:

1. Initialize config:

2. Run all 4 tools together:

3. Add CI reports (optional):

4. If your project is a library, start API baseline flow:

Tool Map

Quick Start

Common examples:

Detailed options and output contracts for each tool are documented in the sections below.

Public API

The package-facing checker gateways live directly under src/:

• Infocyph\PHPProbe\SyntaxChecker
• Infocyph\PHPProbe\DuplicateChecker
• Infocyph\PHPProbe\ApiSnapshotChecker
• Infocyph\PHPProbe\CommentChecker

All expose:

$args is the same argument list that follows the CLI subcommand. For example:

Everything else is internal implementation detail, grouped by role:

Config Lookup

The default config filename is phpprobe.json.

When a checker needs a config file and --config was not passed, PHPProbe resolves it in this order:

1. phpprobe.json in the current project root, meaning the current working directory.
2. vendor/infocyph/phpprobe/resources/phpprobe.json under the current project root.
3. resources/phpprobe.json only when the current project itself is infocyph/phpprobe.

If no config can be found, PHPProbe throws a runtime config error.

Preset files are bundled resources. They are resolved from:

1. vendor/infocyph/phpprobe/resources/presets/<name>.json.
2. resources/presets/<name>.json only while developing infocyph/phpprobe itself.

Project-root preset files are not looked up automatically.

When --config=FILE is passed explicitly and that file is missing, unreadable, empty, or invalid JSON, PHPProbe treats it as an empty config and continues with internal defaults plus any CLI options.

Config Format

The bundled resources/phpprobe.json is intentionally small:

A full project config may override any part of the selected preset:

Config keys accept snake case, kebab case and camel case. For example, min_tokens, min-tokens and minTokens are equivalent. Excludes can be configured as either exclude or exclude_paths. duplicates.ignore_fingerprints suppresses known clone fingerprints without a baseline file. comments.rules lets you toggle rule enabled and override per-rule severity.

Internal duplicate defaults, before any preset is applied, are mode=gate, normalize=true, fuzzy=false, near_miss=false, min_lines=5, min_tokens=70, min_statements=4, min_similarity=0.85, no baseline, no JSON output and no configured paths or excludes.

Internal API defaults are include_protected=true, no baseline, no JSON output and no configured paths or excludes.

Config merge order is:

1. Internal checker defaults.
2. Config-file preset, when present.
3. Explicit values in the config file.
4. CLI --preset=NAME, when present.
5. Explicit CLI flags and CLI paths.

Local config values override the config-file preset. CLI --preset is a run-level override and can override config-file values. Explicit CLI flags still win after that.

Presets

Preset templates live in resources/presets/ and are loaded by Infocyph\PHPProbe\Config\PresetRepository.

Available presets:

The standard, ci, and strict presets include the same default syntax, duplicate, API and comment excludes:

Their duplicate sections also exclude storage/framework/views.

Preset commands:

presets prints one preset name per line. preset <name> prints the bundled JSON template. Unknown preset names print an error and exit 2. Legacy alias phpstorm is still accepted and resolves to standard.

Combined Check Command

check runs syntax, duplicates, api, and comments in sequence and returns a combined exit code.

Options:

Exit behavior:

• If any checker exits 2, combined exit is 2.
• Else if any checker exits non-zero, combined exit is 1.
• Otherwise combined exit is 0.

Config Validate Command

Options:

• --config=FILE (default ./phpprobe.json)
• --json (machine-readable result)
• --help

Returns 0 for valid config, 1 for schema/key/type validation errors, and 2 for missing/unreadable/invalid JSON files.

Init Command

Options:

• --preset=NAME (default, standard, ci, strict; default standard)
• --path=FILE (default ./phpprobe.json)
• --with-ci (also writes .github/workflows/phpprobe.yml)
• --force (overwrite existing files)
• --help

Doctor Command

Options:

• --config=FILE (default ./phpprobe.json)
• --json
• --help

Checks include PHP version, required extensions, config validity, and CaptainHook presence.

Syntax Checker

The syntax checker discovers PHP files, then runs PHP's native lint command against each file:

Command:

Options:

Path behavior:

• CLI paths override syntax.paths from config.
• If CLI paths are empty, syntax.paths is used.
• If both are empty, discovery starts from ..
• Config excludes and CLI excludes are merged.

Output and exits:

JSON note: comment findings include confidence, subtype, explanation, suggestion, and autofix (suggestion metadata) when available. | Unknown preset | stderr: preset error | 2 |

Comment Policy Checker

The comment checker scans PHP comments using token_get_all() and reports marker tags and commented-out code policy findings.

Command:

Options:

Config-only options:

• comments.rules allows per-finding overrides such as { "comment_marker": { "enabled": false } } or { "commented_out_code_with_weak_reason": { "severity": "info" } }.
• comments.doc_mode accepts heuristic, parser, or hybrid.
• comments.fail_confidence accepts low, medium, or high.
• comments.doc_signature_consistency enables signature-vs-PHPDoc consistency checks.
• comments.doc_type_hygiene enables PHPDoc tag/type hygiene checks.
• comments.explain enables explanation and suggestion details.
• comments.baseline and comments.write_baseline map to comment baseline CLI flags.
• comments.doc_cache configures persistent PHPDoc parse cache with enabled and file.
• comments.custom_rules allows regex-based project-specific rules (id, pattern, severity, message, enabled, scope).

Comment policy and PHPDoc checks

1. Marker detection: tags like TODO, FIXME, BUG, HACK, SECURITY, REVIEW, DEPRECATED.
2. Commented-out code requires directly attached tagged reason.
3. Long commented-out blocks require an issue reference.
4. Oversized commented-out blocks are always reported.
5. Dead suppressions are surfaced for cleanup.
6. PHPDoc signatures/tag values are validated against native declarations.

Default thresholds:

• min_reason_length = 12
• require_issue_for_blocks_longer_than = 3
• max_allowed_block_lines = 10

Policy-to-finding mapping:

Inline suppression format:

• @phpprobe-ignore RULE_ID
• @phpprobe-ignore RULE_A,RULE_B until=YYYY-MM-DD
• @phpprobe-ignore RULE_ID scope=symbol
• @phpprobe-ignore RULE_ID scope=symbol symbol=ClassName::method

Comment baseline usage:

Output and exits:

Public API Snapshot Checker

The API checker parses PHP files with nikic/php-parser, extracts the package-visible surface and can compare it with a saved snapshot. It is intended for library BC drift checks, not type analysis.

Command:

Options:

Path behavior:

• CLI paths override api.paths from config.
• If CLI paths are empty, api.paths is used.
• If both are empty, discovery starts from ..
• Config excludes and CLI excludes are merged.

Snapshot contents:

• named classes, interfaces, traits and enums
• top-level namespaced functions
• top-level namespaced constants
• public members always
• protected members unless --public-only is used
• class modifiers, inheritance, implemented interfaces, method signatures, property signatures, constants, enum cases, function signatures and stable fingerprints

Output and exits:

Duplicate Checker

The duplicate checker combines token fingerprints, AST block structure, statement windows, near-miss similarity, grouping, pruning, ranking and optional baseline suppression.

Command:

Options:

Config-only options:

• duplicates.ignore_fingerprints accepts a list of clone fingerprints to suppress without using a baseline file.
• duplicates.output.style accepts compact or classic.
• duplicates.output.score_colors lets you tune score thresholds and ANSI colors per band.

Exact accepted forms matter: numeric options, --mode, --baseline and valued --write-baseline=FILE are parsed in equals form. --config, --preset and --exclude also accept split form. --write-baseline may also be passed as a bare flag.

Path behavior:

• CLI paths override duplicates.paths from config.
• If CLI paths are empty, duplicates.paths is used.
• If both are empty, discovery starts from ..
• Config excludes and CLI excludes are merged.

Mode behavior:

• gate: token-window duplicate detection only, unless --near-miss is explicitly passed.
• audit: token-window matching plus statement-window matching and near-miss matching is enabled automatically.

Output and exits:

Duplicate Detection Details

File discovery:

• PHPProbe first tries git ls-files -z --cached --others --exclude-standard.
• It filters discovered PHP files with git check-ignore -z --stdin --no-index.
• If Git discovery is unavailable, it recursively scans the selected paths.
• Recursive fallback skips common infrastructure directories such as .git, .idea, .phpunit.cache, .psalm-cache, .vscode, coverage, node_modules and vendor.

Token normalization:

• Whitespace, comments, doc comments, PHP open tags and close tags are ignored.
• With normalize=true, variables become VAR, numbers become NUM, strings become STR.
• With fuzzy=true, identifiers and names become ID.
• With --exact, token values include token names and original text.

Token clones:

• PHPProbe hashes every normalized token window of min_tokens tokens.
• Matching windows are candidate clones.
• Candidates are extended token-by-token to find the full matching region.
• Overlapping windows in the same file are ignored.
• Clone regions below min_lines are ignored.

AST and statement matching:

• PHPProbe uses nikic/php-parser to index structural blocks.
• Indexed blocks include functions, methods, closures, arrow functions, loops, branches, match arms and try/catch/finally blocks.
• Statement hashes are built from AST shape.
• In audit mode, matching statement windows of min_statements statements are reported as statement clones.

Near-miss matching:

• Near-miss matching compares blocks with the same block type.
• Similarity is weighted as 72% statement-hash similarity and 28% AST-shape similarity.
• Similarity is based on longest-common-subsequence ratio.
• Matches below min_similarity are ignored.

Grouping, pruning and scoring:

• Duplicate pairs are grouped into clone families.
• Contained/weaker clones are pruned.
• Results are ranked by score, line span and similarity.
• Scoring rewards larger clones, more occurrences, higher similarity, structural completeness and near-miss signal; small trivial clones are penalized.

Duplicate JSON Result Shape

phpprobe duplicates --json emits:

Clone source is one of:

• tokens
• statements
• near_miss

known_clones is populated when a duplicate baseline is read. new_clones is the number of clone groups remaining after baseline suppression.

API JSON Result Shape

phpprobe api --json emits:

Baselines

Write a baseline:

Use a baseline:

This repository does not use a duplicate baseline in CI; duplicate findings are expected to be resolved directly.

Duplicate baseline files contain:

API baseline files use the same top-level version, generated_at and symbols shape emitted under the snapshot JSON key. Missing, unreadable, or invalid baseline files now fail with exit code 2. Duplicate baseline files follow the same strict behavior: missing, unreadable, or invalid baselines fail with exit code 2.

Colored Output

Checker text output is colorized on interactive terminals:

• green: successful summaries
• yellow: warning/medium severity lines
• red: error/high/critical summaries
• cyan: baseline write notifications

You can override these globally for all checker text output with root-level output.colors:

Color output is automatically disabled for non-TTY streams and when NO_COLOR is set (or TERM=dumb), so CI logs and JSON output stay clean.

CI / Cloud

Workflow: .github/workflows/ci.yml

CI runs:

1. PHPProbe matrix on PHP 8.2, 8.3, 8.4, 8.5:
   • composer validate --strict
   • composer test
   • composer lint
   • composer duplicates
   • composer api
   • composer comments
2. PHPForge integration:
   • checks out infocyph/phpforge
   • injects local phpprobe via Composer path repository
   • runs PHPForge tests

workflow_dispatch supports phpforge_ref to test a specific PHPForge branch/tag/SHA.

Development

Composer scripts:

Useful local checks: