PHPuboCop

PHPuboCop is a RuboCop-inspired linter for PHP projects.

Goals

• Bring Ruby-style strictness and consistency to PHP code.
• Keep rules composable and easy to extend.
• Work as a normal Composer library + executable binary.

Installation

composer require --dev cyjimmy264/phpubocop

Usage

vendor/bin/phpubocop
vendor/bin/phpubocop src
vendor/bin/phpubocop src tests
vendor/bin/phpubocop src --format=json
vendor/bin/phpubocop src --config=.phpubocop.yml
vendor/bin/phpubocop src --autocorrect
vendor/bin/phpubocop src --autocorrect-all
vendor/bin/phpubocop src --verbose

# Allow Xdebug for debugging/profiling runs.
PHPUBOCOP_ALLOW_XDEBUG=1 vendor/bin/phpubocop src

phpubocop disables Xdebug by default by re-executing itself with xdebug.mode=off, because Xdebug significantly slows down lint runs. Set PHPUBOCOP_ALLOW_XDEBUG=1 when you explicitly want to debug or profile the process.

Exit code:

• 0 if no offenses were found.
• 1 if at least one offense was found.
• Files ignored by the project's .gitignore are skipped automatically.
• --autocorrect applies only cops explicitly marked as safe for autocorrection.
• --autocorrect-all applies all autocorrectable cops, including unsafe ones.
• --verbose prints selected config source and file discovery stats to STDERR.
• Default text output uses RuboCop-like progress markers per file (., C, W, E, F) plus detailed offense lines.

Configuration

Create .phpubocop.yml:

AllCops:
  EnabledByDefault: true
  UseGitFileList: true
  Exclude:
    - vendor/**

Layout/LineLength:
  Enabled: true
  Max: 120

Layout/TrailingCommaInMultiline:
  Enabled: true

Layout/TrailingWhitespace:
  Enabled: true

Layout/IndentationStyle:
  Enabled: true
  Style: spaces
  TabWidth: 4

Style/DoubleQuotes:
  Enabled: true

Style/EmptyCatch:
  Enabled: true

Style/MultilineTernary:
  Enabled: true

Style/BooleanLiteralComparison:
  Enabled: true

Style/StrictComparison:
  Enabled: true

Security/Unserialize:
  Enabled: true

Security/Exec:
  Enabled: true

Security/EvalAndDynamicInclude:
  Enabled: true

Lint/DuplicateArrayKey:
  Enabled: true

Lint/DuplicateMethod:
  Enabled: true

Lint/EvalUsage:
  Enabled: true

Lint/SuppressedError:
  Enabled: true

Lint/ShadowingVariable:
  Enabled: true

Lint/UnreachableCode:
  Enabled: true

Lint/UselessAssignment:
  Enabled: true

Lint/UnusedVariable:
  Enabled: true
  IgnorePrefixedUnderscore: true
  IgnoreParameters: true

Metrics/AbcSize:
  Enabled: true
  Max: 17

Metrics/CyclomaticComplexity:
  Enabled: true
  Max: 7

Metrics/MethodLength:
  Enabled: true
  Max: 20
  CountAsOne:
    - array
    - heredoc
    - call_chain

Metrics/PerceivedComplexity:
  Enabled: true
  Max: 8

Metrics/ParameterLists:
  Enabled: true
  Max: 5

Included cops (MVP)

• Layout/TrailingWhitespace
• Layout/LineLength
• Layout/TrailingCommaInMultiline
• Layout/IndentationStyle
• Style/DoubleQuotes
• Style/EmptyCatch
• Style/MultilineTernary
• Style/BooleanLiteralComparison
• Style/StrictComparison
• Security/Unserialize
• Security/Exec
• Security/EvalAndDynamicInclude
• Lint/DuplicateArrayKey
• Lint/DuplicateMethod
• Lint/EvalUsage
• Lint/SuppressedError
• Lint/ShadowingVariable
• Lint/UnreachableCode
• Lint/UselessAssignment
• Lint/UnusedVariable
• Metrics/AbcSize
• Metrics/CyclomaticComplexity
• Metrics/MethodLength
• Metrics/PerceivedComplexity
• Metrics/ParameterLists
• Architecture/ThinLayerBoundary
• Architecture/ThinLayerComplexity
• Architecture/ThinLayerLength
• Architecture/ThinLayerSuperglobalUsage
• Architecture/ThinLayerForbiddenFunctions
• Architecture/ThinLayerForbiddenMethodCalls
• Architecture/ThinLayerGlobalStateUsage
• Architecture/ThinLayerIncludeUsage
• Architecture/ThinLayerForbiddenStaticCalls

Thin-layer family documentation: docs/thin-layer-cops.md

Architecture

• CopInterface defines one rule.
• Runner applies enabled cops to discovered PHP files.
• ConfigLoader merges defaults with .phpubocop.yml.
• Formatters output in text or JSON.

Roadmap

• Auto-correct support (--autocorrect) for safe cops.
• Namespaced cop packs (e.g. Rails, Laravel, Doctrine).
• More style cops that mirror RuboCop semantics where meaningful in PHP.
• Baseline file support for incremental adoption.
• SARIF and GitHub Actions annotations.