README

custos

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

Documentation · Getting started · Rules · Editors

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, and in any editor as a language server.

Its rule catalogue is modelled on Php Inspections (EA Extended), and rule IDs are compatible: existing @noinspection XxxInspection comments keep working. 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

Release archives 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 analyse --generate-baseline custos-baseline.json   # adopt on legacy code
custos explain OneTimeUseVariables        # what a rule does, its options
custos lsp                                # language server over stdio

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]

Highlights

178 rules in 12 groups: probable bugs, performance, security, control flow, code style, unused code, PHPUnit, language-level migration… (reference)
Quick-fixes for over a hundred rules, applied by custos fix or as editor code actions.
Version-aware: rules follow the target PHP version from custos.json or composer.json.
CI-ready: text, JSON, Checkstyle, GitHub annotations and SARIF output; baselines for legacy code. (CI recipes)
Editor integration through LSP: Neovim, Helix, VS Code, PhpStorm, Sublime Text, Emacs. (setup)

Configuration

An optional custos.json at the project root:

{
  "php": "8.3",
  "paths": ["src", "tests"],
  "baseline": "custos-baseline.json",
  "rules": {
    "MultipleReturnStatements": { "enabled": false },
    "OneTimeUseVariables": { "options": { "ALLOW_LONG_STATEMENTS": false } }
  }
}

All keys are described in Configuration.

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         # 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