README

custos

Fast PHP inspector and fixer.
Rules with quick-fixes · one static binary · CLI, CI, LSP and MCP

Documentation · Getting started · Rules · Editors · AI agents

custos finds probable bugs, performance and security issues, needless complexity and outdated constructs in PHP code (PHP 5.3 to 8.5), and fixes many of them for you. It is written in Go with its own PHP parser and type inference, so it needs no PHP runtime. It runs from the command line, in CI, in editors as a language server, and with AI agents through MCP.

The catalogue mixes rules modeled on Php Inspections (EA Extended), whose existing @noinspection XxxInspection comments keep working, and native rules designed for custos. custos is an independent clean-room implementation (see NOTICE).

Install

brew install janalis/tap/custos           # macOS / Linux
composer require --dev janalis/custos     # per project → vendor/bin/custos

Archives and bare binaries for Linux, macOS and Windows (amd64/arm64) are on the releases page. See Installation for details and building from source.

Quick start

custos analyse                            # report problems in the project
custos fix --dry-run --diff src           # preview quick-fixes
custos fix src                            # apply them
custos explain OneTimeUseVariables        # what a rule does, its options
custos mcp --root /path/to/project        # MCP server for AI agents

src/Invoice.php:3:5: warning: Variable $total is used only once; inline its value. [OneTimeUseVariables] (fixable)
src/Invoice.php:7:6: error: Restrict the classes unserialize() may create via its second argument. [UnserializeExploits]

More in the guide: command line, baseline for legacy code, CI recipes, editor setup, MCP setup and the rule reference.

Configuration

An optional custos.json at the project root pins the PHP version, chooses paths and turns rules on or off; see Getting started for an example and Configuration for every key.

Contributing

Contributions are welcome: bug reports with a PHP snippet, false positives, fixes. Read CONTRIBUTING.md and the contributor guide. Please note the clean-room rule: no code or text from the upstream plugin may enter this repository.

make build          # → bin/custos
make verify         # architecture + lint + tests + fixtures + 100 % coverage + clean-room scan

License

MIT. Builtin symbol data from JetBrains phpstorm-stubs (Apache-2.0). See NOTICE.

janalis / custos

Package info

Security

Statistics