Download the PHP package cosmira/soda without Composer

Soda

Soda checks PHP code for oversized methods, complex conditions, naming problems, and structural issues. It reports what failed and where, with a non-zero exit status when violations are found.

Requires PHP 8.2 or higher.

The first check needs no configuration: Soda uses its standard rules when it finds no soda.php. Vendor directories are excluded automatically.

Configure once, run daily

Create soda.php in your project root. Choose named classes and pass their options:

Exclude generated directories or caches with ->exclude([__DIR__.'/generated']). Configuration exclusions and CLI --exclude values are combined.

Then run:

Only the listed rules run. Remove a rule to disable it. To use the whole standard set, pass RuleCatalog::standard() to with(); import Cosmira\Soda\Config\RuleCatalog. vendor/bin/soda init can generate an expanded, editable configuration equivalent to RuleCatalog::standard(), including its thresholds and readonly-data and boolean-method policies. The standard bundle also includes RepresentationChurn research: its findings appear separately and do not fail the quality gate. Save their evidence with --research-json=build/soda-research.json. Optional rules remain opt-in.

Useful commands

Use the same check command in CI. Exit status 0 means no violations; 1 means a failed check or a configuration/input error. Soda complements a formatter and PHPStan or Psalm by checking code structure and maintainability.

Learn more

• Configuration: paths, thresholds and rule sets.
• Rules and examples: structure, complexity and naming.
• Custom rules: implement a named PHP class.
• Report JSON: machine-readable results.
• Project flow: where parsing, checks and reporting happen.
• Design philosophy: concerns, fluent APIs and value objects with executable examples.
• Research metrics: cognitive complexity, cohesion, measurement limits and corpus reproduction.
• Migration: changed namespaces and extension contracts.

Rule authors can inspect available facts with vendor/bin/soda list:metrics. Expression syntax is an optional implementation tool inside a rule class.

Development

Clone this repository and run composer install. Inside the Soda repository, use php soda in place of vendor/bin/soda. Run composer test for behavioral tests and composer ci for the full project checks.

Licensed under the MIT License.

Explicit behavior checks

The standard set also reports internal factories that only forward construction arguments (NoTrivialFactories) and compound own-state conditions repeated in three or more methods (NoRepeatedCompoundConditions). These are opinionated structural checks: they do not prove an abstraction is useless or two decisions have the same meaning. See the factory examples and repeated-condition examples.

The standard set also includes NoIdenticalBranches (repeated explicit match results and identical full ternary branches) and NoNestedTernary (a full ternary directly inside another full ternary's result branch). Both have narrow syntax boundaries and no automatic fixes. See the examples.

The standard set also includes NoAssignmentInReturn and NoChainedAssignments: make state changes explicit instead of hiding them in returned expressions or combining multiple writes into one chain. See return assignments and assignment chains.

Owner behavior recommendations

Six standard checks identify copied or scattered concerns, fragmented owner operations, repeated object configuration, and repeated decisions or updates over foreign state. Their diagnostics suggest traits, owner methods, or fluent objects with source evidence. See configuration, examples, and boundaries.

Expressions and local state

The standard set also includes NoUnneededTernary (opposite literal boolean branches) and NoReturnInFinally (returns that can override pending results or exceptions), NoReassignedParameters, MaxConsecutiveLocalAssignments(8) and NoRepeatedStringLiterals(3). All five run by default. Repeated-literal checks exclude literal array keys, parameter checks accept a narrow entry normalization, and return-assignment checks accept direct lazy initialization with ??=, named owner-state returns and concise arrow state callbacks. Each exception has a strict-mode option. See the calibration against Soda and pinned Laravel sources. See Expressions and local state for configuration, examples, scope boundaries and intentional exceptions.

Statement limits

The standard set includes MaxStatementsPerCallable(20): at most 20 executable statements per function, method or closure, counted independently of formatting. Nested callables have separate counts. See statement counting for the precise boundaries and threshold configuration.

Namespace dependency restrictions

ForbiddenDependencies is opt-in because each project defines its own module boundaries. Map source namespace prefixes to target prefixes they must not depend on:

Here App\Domain cannot reference types in App\Infrastructure or App\Http, including their descendant namespaces. The reverse direction remains allowed. The rule checks direct class and trait type references, even without a dependency cycle. Unused imports and dynamic string references are outside this check. See module restrictions for matching semantics and analysis boundaries.

The standard bundle includes NoEmptyFinallyBlocks, MaxCognitiveComplexity(15), MaxEfferentCoupling(15), and NoDependencyCycles().