Skip to content
Back to search

PhpCodeArcheology

PHP static analysis for architecture & maintainability — 60+ metrics, complexity analysis, dependency graphs, git churn hotspots, and AI-ready MCP server. Alternative to PHPMetrics.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/phpcodearcheology--phpcodearcheology/badge.svg)](/listings/phpcodearcheology--phpcodearcheology)

HTML

<a href="/listings/phpcodearcheology--phpcodearcheology"><img src="/api/listings/phpcodearcheology--phpcodearcheology/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

composer require --dev php-code-archeology/php-code-archeology
./vendor/bin/phpcodearcheology

No config file needed — the tool works out of the box. It scans your `src` directory and creates an HTML report in `tmp/report`. Open `tmp/report/index.html` in your browser.

> **Tip:** Add `tmp/report` to your `.gitignore` to keep generated reports out of version control.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 588 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/logo.svg" width="80" alt="PhpCodeArcheology Logo">
  3. </p>
  4. # PhpCodeArcheology
  5. [![Packagist Version](https://img.shields.io/packagist/v/php-code-archeology/php-code-archeology)](https://packagist.org/packages/php-code-archeology/php-code-archeology)
  6. [![PHP Version](https://img.shields.io/packagist/php-v/php-code-archeology/php-code-archeology)](https://packagist.org/packages/php-code-archeology/php-code-archeology)
  7. [![License](https://img.shields.io/packagist/l/php-code-archeology/php-code-archeology)](https://packagist.org/packages/php-code-archeology/php-code-archeology)
  8. [![PhpCodeArcheology MCP server](https://glama.ai/mcp/servers/PhpCodeArcheology/PhpCodeArcheology/badges/score.svg)](https://glama.ai/mcp/servers/PhpCodeArcheology/PhpCodeArcheology)
  9. **PhpCodeArcheology** is a PHP static analysis tool that measures code quality through 60+ metrics including cyclomatic complexity, maintainability index, coupling, and cohesion. It generates comprehensive reports for files, classes, methods, and functions — detecting code smells, identifying hotspots via git churn analysis, and tracking quality trends over time.
  10. Unlike PHPStan or Psalm (which focus on type safety and bug detection), PhpCodeArcheology focuses on **architecture and maintainability** — giving you the insights you need to understand and improve your codebase structure. Think of it as an alternative to PHPMetrics with deeper git integration, baseline management, and AI-ready output.
  11. ![PhpCodeArcheology Dashboard](docs/screenshot-dashboard-v2.8.0.png)
  12. ## Features
  13. - **60+ code quality metrics** per file, class, and function — cyclomatic complexity, cognitive complexity, maintainability index, LCOM, Halstead metrics, coupling, instability, and more
  14. - **Problem detection** with 14 built-in rules — God Class, too complex, dead code, security smells, SOLID violations, deep inheritance, low type coverage, untested complex code
  15. - **Test analysis** — auto-detects PHPUnit/Pest/Codeception, maps test files to production classes, integrates Clover XML for line-level coverage, highlights untested hotspots
  16. - **Git integration** — churn analysis, hotspot detection (high churn + high complexity), author tracking
  17. - **Source code display** — view method source code directly in the HTML report with PHP syntax highlighting and a nesting-depth heatmap that reveals complexity hotspots at a glance ([details below](#source-code-display))
  18. - **Multiple report formats** — interactive HTML, Markdown, JSON, SARIF (GitHub Code Scanning), AI summary, Knowledge Graph (JSON)
  19. - **Health Score** — single 0-100 score with A-F grading for your entire project
  20. - **Technical Debt Score** — weighted problem score normalised per 100 logical lines of code
  21. - **History tracking** — trend charts across multiple analysis runs
  22. - **Baseline management** — track only new problems, ignore existing ones (ideal for legacy projects)
  23. - **CI/CD ready** — configurable exit codes, SARIF for GitHub Code Scanning, JSON for custom tooling
  24. - **Quick mode** — fast terminal-only output without report generation
  25. - **CLAUDE.md generation** — auto-generated project overview for AI coding assistants
  26. - **AI integration** — native MCP server for AI assistants like Claude Code ([details below](#ai-integration-mcp-server))
  27. ## Quick Start
  28. ```bash
  29. composer require --dev php-code-archeology/php-code-archeology
  30. ./vendor/bin/phpcodearcheology
  31. ```
  32. No config file needed — the tool works out of the box. It scans your `src` directory and creates an HTML report in `tmp/report`. Open `tmp/report/index.html` in your browser.
  33. > **Tip:** Add `tmp/report` to your `.gitignore` to keep generated reports out of version control.
  34. ## Table of Contents
  35. - [Prerequisites](#prerequisites)
  36. - [Installation](#installation)
  37. - [Using the Composer Plugin](#using-the-composer-plugin)
  38. - [CLI Options](#cli-options)
  39. - [Subcommands](#subcommands)
  40. - [Configuration](#configuration)
  41. - [Test Analysis](#test-analysis)
  42. - [Report Types](#report-types)
  43. - [Source Code Display](#source-code-display)
  44. - [Knowledge Graph Export](#knowledge-graph-export)
  45. - [Key Metrics](#key-metrics)
  46. - [AI Integration (MCP Server)](#ai-integration-mcp-server)
  47. - [Understanding the Health Score](#understanding-the-health-score)
  48. - [Memory and Performance](#memory-and-performance)
  49. - [A Note on Metric Accuracy (v2.7.0)](#a-note-on-metric-accuracy-v270)
  50. - [Development](#development)
  51. - [Roadmap](#roadmap)
  52. - [Contributing](#contributing)
  53. ## Prerequisites
  54. - PHP 8.2 or higher (works on 8.2, 8.3, 8.4, 8.5)
  55. - Composer
  56. ## Installation
  57. ```bash
  58. composer require --dev php-code-archeology/php-code-archeology
  59. ```
  60. ### Global Installation
  61. ```bash
  62. composer global require php-code-archeology/php-code-archeology
  63. ```
  64. Make sure `~/.composer/vendor/bin` (or `~/.config/composer/vendor/bin`) is in your `$PATH`. Then run from any directory:
  65. ```bash
  66. phpcodearcheology /path/to/your/project
  67. ```
  68. ### Docker
  69. ```bash
  70. docker build -t phpcodearcheology https://github.com/PhpCodeArcheology/PhpCodeArcheology.git
  71. ```
  72. Run against a local project:
  73. ```bash
  74. docker run --rm -v "$(pwd)":/project -v "$(pwd)/report":/output phpcodearcheology /project
  75. ```
  76. This mounts your project into the container and writes the HTML report to `./report/`.
  77. ### PHAR (for legacy codebases)
  78. If your project has dependency conflicts with PhpCodeArcheology's requirements (e.g. an older `nikic/php-parser` version), download the standalone PHAR from the [Releases](https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases) page. The PHAR ships all dependencies bundled, so it works without touching your project's `composer.json`.
  79. ```bash
  80. # Download the PHAR and checksum from the latest release
  81. curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar
  82. curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar.sha256
  83. # Verify checksum
  84. shasum -a 256 -c phpcodearcheology.phar.sha256 # macOS
  85. sha256sum -c phpcodearcheology.phar.sha256 # Linux
  86. # Run it (PHP 8.2+)
  87. php phpcodearcheology.phar --quick src/
  88. ```
  89. Use the PHAR when: your project's dependencies collide with PhpCodeArcheology's, you want a CI step without a `composer require --dev`, or you analyse a legacy codebase where adding dev-deps is risky.
  90. ## Using the Composer Plugin
  91. PhpCodeArcheology registers itself as a Composer plugin, so you can run the analysis directly via Composer:
  92. ```bash
  93. composer codearch:analyze
  94. ```
  95. When no path is given and no config file exists, it automatically detects your PSR-4 source directories from `composer.json`. All CLI options are supported:
  96. ```bash
  97. composer codearch:analyze -- --quick
  98. composer codearch:analyze -- --report-type=json --coverage-file=clover.xml
  99. composer codearch:analyze -- src/ lib/
  100. ```
  101. To create a config file interactively:
  102. ```bash
  103. ./vendor/bin/phpcodearcheology init
  104. ```
  105. ## CLI Options
  106. ```
  107. ./vendor/bin/phpcodearcheology [options] [path...]
  108. ```
  109. | Option | Description |
  110. |--------|-------------|
  111. | `--report-type=TYPE` | Report format: `html` (default), `markdown`, `json`, `sarif`, `ai-summary`, `graph`. Comma-separated for multiple: `html,json` |
  112. | `--report-dir=DIR` | Output directory (default: `tmp/report`) |
  113. | `--quick` | Fast analysis with terminal output only, no report generation |
  114. | `--no-color` | Disable coloured terminal output (also respects `NO_COLOR` env) |
  115. | `--fail-on=LEVEL` | Exit 1 on `error` or `warning` (for CI pipelines) |
  116. | `--generate-claude-md` | Generate a `CLAUDE.md` project overview |
  117. | `--git-root=DIR` | Git repository root (default: current directory) |
  118. | `--extensions=EXT` | File extensions to analyse (comma-separated, default: `php`) |
  119. | `--exclude=DIR` | Directories to exclude (comma-separated) |
  120. | `--coverage-file=FILE` | Clover XML coverage file from PHPUnit/Pest for line-level coverage data |
  121. | `--source-code` | Include source code with syntax highlighting and nesting heatmap in the HTML report ([details below](#source-code-display)) |
  122. | `--version` | Show version |
  123. ## Subcommands
  124. ### `init` — Create Config File
  125. ```bash
  126. ./vendor/bin/phpcodearcheology init
  127. ```
  128. Interactively creates a `php-codearch-config.yaml` with sensible defaults. Detects common source directories (`src`, `app`, `lib`) automatically.
  129. ### `compare` — Compare Two Reports
  130. ```bash
  131. ./vendor/bin/phpcodearcheology compare report-before.json report-after.json
  132. ```
  133. Shows a delta view of metrics, problem counts, and lists new/resolved problems. Useful for answering: "Did my refactoring actually help?"
  134. ### `baseline` — Track New Problems Only
  135. ```bash
  136. ./vendor/bin/phpcodearcheology baseline create src
  137. ./vendor/bin/phpcodearcheology baseline check src
  138. ```
  139. `create` saves the current problem set as a baseline. `check` runs a fresh analysis and reports only problems that are **new** compared to the baseline. Returns exit code 1 if new errors are found — ideal for CI pipelines on legacy projects.
  140. ## Configuration
  141. Create a `php-codearch-config.yaml` in your project root (or use `init`):
  142. ```yaml
  143. include:
  144. - "src"
  145. exclude:
  146. - "vendor"
  147. extensions:
  148. - "php"
  149. packageSize: 2
  150. reportDir: "tmp/report"
  151. reportType: "html"
  152. git:
  153. enable: true
  154. since: "6 months ago"
  155. root: "." # Git repository root (useful for monorepos or subdirectory analysis)
  156. graph:
  157. methodCalls: true # Track cross-class method calls in the knowledge graph (default: true)
  158. php:
  159. version: "8.2" # Target PHP version for parsing (default: host PHP version)
  160. shortOpenTags: false # Treat <? as PHP open tag (default: false)
  161. framework:
  162. detect: true # Auto-detect Symfony/Laravel/Doctrine from composer.json (default: true)
  163. adjustments:
  164. doctrineCycles: true # Downgrade Entity↔Repository cycles to info (default: true)
  165. entityCycles: true # Downgrade Entity↔Entity ORM cycles to info (default: true)
  166. controllerThresholds: true # Raise dependency thresholds for controllers (default: true)
  167. qualityGate:
  168. maxErrors: 0
  169. maxWarnings: 10
  170. thresholds:
  171. tooLong:
  172. file: 400
  173. class: 300
  174. function: 40
  175. method: 30
  176. tooComplex:
  177. cc: 10
  178. ccLargeCode: 20
  179. difficulty: 20
  180. cognitiveComplexity: 15
  181. avgMethodCc: 10
  182. tooManyParameters:
  183. warning: 4
  184. error: 7
  185. tooDependent:
  186. function: 10
  187. class: 20
  188. lowTypeCoverage:
  189. warning: 60
  190. error: 40
  191. deepInheritance:
  192. warning: 4
  193. error: 6
  194. tooMuchHtml:
  195. filePercent: 25
  196. classPercent: 10
  197. fileOutput: 10
  198. classOutput: 4
  199. hotspot:
  200. minChurn: 10
  201. minCc: 15
  202. lcomExclude:
  203. patterns: # Class name patterns to skip LCOM warnings (fnmatch)
  204. - "*Exception"
  205. - "*Error"
  206. interfaces: # Implemented interfaces that justify low cohesion
  207. - "EventSubscriberInterface"
  208. - "EventListenerInterface"
  209. ```
  210. > **Note:** Enums, interfaces, traits, and classes with 0-1 methods are always excluded from LCOM warnings regardless of configuration.
  211. All threshold values shown above are the defaults. You only need to specify values you want to override.
  212. ## Test Analysis
  213. PhpCodeArcheology automatically detects your test infrastructure from `composer.json` (PHPUnit, Pest, or Codeception) and maps test files to production classes using PSR-4 namespaces, naming conventions, and directory structure.
  214. **What you get out of the box:**
  215. - Per-class `hasTest` flag and test file count in the HTML/Markdown/JSON reports
  216. - `UntestedComplexCode` warnings for classes with cyclomatic complexity ≥ 8 and no tests (only when test infrastructure is detected)
  217. - `untested` as a refactoring priority driver
  218. - A **Tests page** in the HTML and Markdown reports with a coverage gaps table and dashboard tiles
  219. **Important note on Pest:** Pest's function-based tests (`it(...)`, `test(...)`) contain no class declaration and cannot be mapped to production classes by name alone. To get accurate coverage for Pest projects, generate a Clover XML report — this tracks actual line execution regardless of test style.
  220. **With Clover XML coverage data** (optional, recommended for Pest), you get line-level coverage per class:
  221. ```bash
  222. # Generate coverage first (requires Xdebug or PCOV PHP extension)
  223. XDEBUG_MODE=coverage vendor/bin/pest --coverage-clover clover.xml
  224. # or: XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover clover.xml
  225. # PhpCodeArcheology auto-detects clover.xml in common locations:
  226. # clover.xml, coverage/clover.xml,
  227. # build/logs/clover.xml, build/coverage/clover.xml,
  228. # var/reports/clover.xml, var/coverage/clover.xml (Symfony layout)
  229. ./vendor/bin/phpcodearcheology src/
  230. # Or specify explicitly via CLI:
  231. ./vendor/bin/phpcodearcheology --coverage-file clover.xml src/
  232. ```
  233. To make the path persistent across runs, set it in your config file:
  234. ```yaml
  235. # php-codearch-config.yaml
  236. coverageFile: var/reports/clover.xml
  237. ```
  238. The CLI flag still takes precedence over the config file value.
  239. Coverage data is factored into the **Health Score** as a 10th factor (10% weight). The `get_test_coverage` MCP tool exposes all coverage data to AI assistants.
  240. ## Report Types
  241. | Type | Subdirectory | Output | Use Case |
  242. |------|-------------|--------|----------|
  243. | `html` | `html/` | Interactive HTML report with charts | Browser-based review |
  244. | `markdown` | `markdown/` | Markdown files | Text-based review, Git-friendly |
  245. | `json` | `json/` | `report.json` | Machine processing, custom tooling |
  246. | `sarif` | `sarif/` | `report.sarif.json` | GitHub Code Scanning, VS Code SARIF Viewer |
  247. | `ai-summary` | `ai-summary/` | `ai-summary.md` | Token-efficient summary for LLM consumption |
  248. | `graph` | `graph/` | `graph.json` | Knowledge Graph (nodes + edges) for AI tools and visualisations |
  249. Since v1.6.0, each report type writes into its own subdirectory. `history.jsonl` remains in the report root.
  250. ```
  251. tmp/report/
  252. ├── html/
  253. │ └── index.html
  254. ├── json/
  255. │ └── report.json
  256. ├── sarif/
  257. │ └── report.sarif.json
  258. ├── markdown/
  259. │ └── ...
  260. ├── ai-summary/
  261. │ └── ai-summary.md
  262. ├── graph/
  263. │ └── graph.json
  264. └── history.jsonl
  265. ```
  266. Generate multiple report types in one run:
  267. ```bash
  268. ./vendor/bin/phpcodearcheology --report-type=html,json
  269. ```
  270. > **Upgrading from v1.5.x?** Old report files in the report root (e.g. `index.html`, `report.json`) are no longer overwritten. They can be safely deleted.
  271. ## Source Code Display
  272. The HTML report can embed the actual source code of methods and functions — with PHP syntax highlighting and a **nesting-depth heatmap** that makes complexity visible at a glance.
  273. ```bash
  274. ./vendor/bin/phpcodearcheology --source-code src/
  275. ```
  276. **What you see:**
  277. - Full PHP source code with syntax highlighting (powered by highlight.js)
  278. - **Nesting heatmap** — lines inside deeper control structures (if/for/while/switch/catch) progressively light up from yellow to red, so the complexity drivers are immediately obvious
  279. - **Problem badges** above the code showing all detected issues (e.g. "Complexity is too high")
  280. - **Severity border** — the code block gets a colored left border matching the worst problem level
  281. **Configuration:**
  282. ```yaml
  283. sourceCode:
  284. enable: true
  285. display: "problems-only" # or "all" for every method/function
  286. ```
  287. - `problems-only` (default with `--source-code`) — only shows source for methods with detected problems, keeping the report size manageable
  288. - `all` — shows source for every method and function
  289. The highlight.js assets are only included in the report when the feature is enabled.
  290. ## Knowledge Graph Export
  291. The `graph` report type exports your codebase structure as a machine-readable Knowledge Graph — designed for AI tools, graph databases, and custom visualisations.
  292. ```bash
  293. ./vendor/bin/phpcodearcheology --report-type=graph --report-dir=output src/
  294. # Writes: output/graph/graph.json
  295. ```
  296. The JSON output contains four top-level arrays:
  297. **`nodes`** — five types of nodes, each with an `id`, `type`, `name`, `metrics`, and `flags`:
  298. | Node type | Metrics |
  299. |-----------|---------|
  300. | `class` | `cc`, `lcom`, `mi`, `instability`, `afferentCoupling`, `efferentCoupling`, `gitChurnCount`, `gitCodeAgeDays` |
  301. | `method` | `cc`, `cognitiveComplexity`, `params` |
  302. | `function` | `cc`, `cognitiveComplexity`, `params` |
  303. | `package` | `abstractness`, `instability`, `distanceFromMainline` |
  304. | `author` | `commitCount`, `filesChanged` |
  305. **`edges`** — relationships between nodes:
  306. | Edge type | Meaning |
  307. |-----------|---------|
  308. | `declares` | Class → Method |
  309. | `extends` | Class → Parent class |
  310. | `implements` | Class → Interface |
  311. | `uses_trait` | Class → Trait |
  312. | `depends_on` | Class → Class (via `new` / static call) |
  313. | `calls` | Method → Method (cross-class calls via `new` / static call, weight = call-site count) |
  314. | `belongs_to` | Class → Package |
  315. | `authored_by` | Class → Author |
  316. | `cycle_member` | Class ↔ Class (dependency cycle, bidirectional) |
  317. **`clusters`** — classes grouped by package.
  318. **`cycles`** — detected dependency cycles with the involved class node IDs.
  319. ```json
  320. {
  321. "version": "1.0",
  322. "generatedAt": "2026-03-24T12:00:00+00:00",
  323. "nodes": [
  324. { "id": "class:x1a2b3c4", "type": "class", "name": "App\\UserService",
  325. "path": "/src/UserService.php",
  326. "metrics": { "cc": 12, "lcom": 3, "mi": 65.2, "instability": 0.8,
  327. "afferentCoupling": 5, "efferentCoupling": 20,
  328. "gitChurnCount": 15, "gitCodeAgeDays": 42 },
  329. "flags": { "interface": false, "trait": false, "abstract": false,
  330. "final": false, "enum": false },
  331. "problems": [] }
  332. ],
  333. "edges": [
  334. { "source": "class:x1a2b3c4", "target": "class:x9c0d1e2f",
  335. "type": "depends_on", "weight": 1 }
  336. ],
  337. "clusters": [
  338. { "id": "package:App\\Services", "name": "App\\Services",
  339. "nodeIds": ["class:x1a2b3c4"] }
  340. ],
  341. "cycles": [
  342. { "nodes": ["class:xabc123", "class:xdef456"], "length": 2 }
  343. ]
  344. }
  345. ```
  346. ## Key Metrics
  347. | Metric | Description |
  348. |--------|-------------|
  349. | **Cyclomatic Complexity (CC)** | Number of independent paths through code. Below 5 is good, above 10 needs attention. |
  350. | **Cognitive Complexity** | How difficult code is to understand (considers nesting depth). |
  351. | **Maintainability Index (MI)** | Composite score from CC, Halstead volume, and LOC. Above 85 is good, below 65 is concerning. |
  352. | **LCOM** | Lack of Cohesion of Methods — how well a class's methods relate to each other. Lower is better. |
  353. | **Halstead Metrics** | Difficulty, effort, volume, and vocabulary based on operators/operands. |
  354. | **Type Coverage** | Percentage of parameters and return values with type declarations. |
  355. | **Instability** | Ratio of efferent to total coupling (0 = stable, 1 = unstable). |
  356. | **Technical Debt Score** | Weighted problem points per 100 logical lines of code. |
  357. | **Health Score** | Overall project quality grade from A (excellent) to F (critical). |
  358. For detailed descriptions, formulas, thresholds, and interpretation guidelines, see the **[Metric Reference](docs/metrics.md)**.
  359. The HTML report also includes a full **Metric Glossary** with descriptions, thresholds, and severity levels.
  360. ## AI Integration (MCP Server)
  361. PhpCodeArcheology includes a native **MCP (Model Context Protocol) server** — AI assistants like Claude can query your codebase analysis results directly, without reading files or parsing JSON manually.
  362. ### Setup with Claude Code
  363. The setup depends on how you installed PhpCodeArcheology:
  364. **Global installation** (`composer global require php-code-archeology/php-code-archeology`):
  365. ```bash
  366. claude mcp add phpcodearcheology -- phpcodearcheology mcp
  367. ```
  368. **Project dependency** (`composer require --dev php-code-archeology/php-code-archeology`):
  369. ```bash
  370. claude mcp add phpcodearcheology -- vendor/bin/phpcodearcheology mcp
  371. ```
  372. Or drop a `.mcp.json` into your project root for team sharing:
  373. ```json
  374. {
  375. "mcpServers": {
  376. "phpcodearcheology": {
  377. "command": "vendor/bin/phpcodearcheology",
  378. "args": ["mcp"]
  379. }
  380. }
  381. }
  382. ```
  383. Once connected, Claude can answer questions like *"Which classes have the highest technical debt?"*, *"Show me all God Classes"*, or *"What are the top refactoring priorities in this project?"* — using live analysis data.
  384. ### Available MCP Tools
  385. | Tool | Description |
  386. |------|-------------|
  387. | `get_health_score` | Overall code health score, grade, and project statistics |
  388. | `get_problems` | Code quality problems, filterable by severity and type |
  389. | `get_metrics` | Detailed metrics for a specific class, file, or function |
  390. | `get_hotspots` | Git hotspots ranked by churn × complexity |
  391. | `get_refactoring_priorities` | Ranked refactoring candidates with recommendations |
  392. | `get_dependencies` | Class dependency analysis (incoming/outgoing) |
  393. | `get_class_list` | All classes with key metrics, sortable and filterable |
  394. | `get_graph` | Knowledge graph as JSON (nodes, edges, cycles) |
  395. | `get_impact_analysis` | Impact analysis: what breaks if you change a method? Shows callers and call chains |
  396. | `get_test_coverage` | Test coverage summary — tested/untested classes, coverage gaps, test mapping |
  397. | `search_code` | Search entities by name with metric overview |
  398. ## Understanding the Health Score
  399. The Health Score (0–100) is a **guideline for tracking trends**, not an absolute judgment of code quality. Some things to keep in mind:
  400. - **Complex domains produce complex code.** A financial calculation engine, a protocol parser, or a compiler will naturally have higher Halstead Difficulty and Cyclomatic Complexity than a REST API. That's expected, not a defect.
  401. - **Scores are most useful over time.** A project that moves from 65 to 72 over six months is improving — even if it never reaches 90.
  402. - **Focus on outliers, not the average.** The most actionable insight is which classes deviate significantly from your project's baseline. Those are your refactoring candidates.
  403. - **Don't compare across projects.** A score of 80 in a Symfony application is not the same as 80 in a CLI tool. Different architectures and domains have different natural complexity floors.
  404. The score is weighted across 10 factors (Maintainability Index, Problem Density, Complexity, Coupling, Code Structure, HTML Ratio, Encapsulation, Dependencies, Abstractness, and Test Coverage). See [`docs/metrics-formulas.md`](docs/metrics-formulas.md) for the exact formulas and weights.
  405. **Further reading:** [How I Use PhpCodeArcheology in Practice](https://www.marcuskober.de/en/blog/how-i-use-phpcodearcheology/) — a real-world walkthrough covering legacy assessment, hotspot discovery, and measuring refactoring success.
  406. ## Memory and Performance
  407. The directories `vendor/`, `node_modules/`, and `.git/` are **excluded automatically** — you don't need to configure this. If you point the tool at your project root, only your own code is analysed.
  408. For **large codebases** (50k+ files), analysis may require more memory than the default 1G. The tool respects your `php.ini` `memory_limit` — if you've set it to `-1` (unlimited), it stays unlimited. To adjust the limit per project, add `memoryLimit` to your config file:
  409. ```yaml
  410. # php-codearch-config.yaml
  411. memoryLimit: "2G" # or "-1" for unlimited
  412. ```
  413. ## A Note on Metric Accuracy (v2.7.0)
  414. I use PhpCodeArcheology extensively on my own projects to track code quality over time. While doing so, I noticed that some metric values didn't quite add up — method-level Halstead difficulty seemed too high, certain classes were flagged as God Classes when they shouldn't have been, and error counts felt inflated.
  415. After a thorough review, I found and fixed several calculation bugs that had been present since earlier versions. The most impactful was a Halstead operand tracking bug at the method level, along with double-counting in complexity predictions, false positives in God Class detection, and a few other issues.
  416. I sincerely apologize for the inaccuracy. A code analysis tool must be trustworthy above all else, and these bugs undermined that. Version 2.7.0 corrects all known calculation issues, and I've added hand-calculated test fixtures to ensure the formulas stay correct going forward.
  417. **What this means for you:** If you're upgrading from an earlier version, your analysis results will change — most notably, error counts will decrease significantly and Health Scores will improve. The tool will show a one-time notice on first run. See [`docs/metrics-formulas.md`](docs/metrics-formulas.md) for a detailed breakdown of every change and its expected impact.
  418. ## Development
  419. The HTML report templates use **Tailwind CSS**. The compiled `output.css` is committed to the repository, so you do **not** need Node.js to use or contribute to this project.
  420. If you modify HTML templates or CSS, rebuild with:
  421. ```bash
  422. npm install
  423. npm run build:css
  424. ```
  425. For live rebuilding during development:
  426. ```bash
  427. npm run watch:css
  428. ```
  429. ## Roadmap
  430. See [ROADMAP.md](ROADMAP.md) for planned features. The next major version (**3.0**) is in development on the `3.0.x` branch — it reworks how relative problem thresholds are calculated, replacing the current "percentage above/below project average" rule with robust statistical outlier detection. Track progress in the [3.0.0 milestone](https://github.com/PhpCodeArcheology/PhpCodeArcheology/milestone/1).
  431. ## Contributing
  432. Contributions are welcome! Check the [open issues](https://github.com/PhpCodeArcheology/PhpCodeArcheology/issues) for bugs and feature requests, or see the [Roadmap](ROADMAP.md) for planned features. For larger changes, open an issue first to discuss the approach.
  433. ## Author
  434. Marcus Kober — [GitHub](https://github.com/marcuskober)
  435. ## License
  436. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.