Mutator Laravel Package

Getting Started

Start by installing the package via Composer:

composer require infection/mutator

The core abstractions are MutatorInterface (for defining custom mutations) and MutatorChain (for composing multiple mutators). Your first use case is likely to generate test-targeted mutations — for example, to verify your test suite’s ability to catch common code changes.
Look at src/Mutator/ in the repository for built-in mutator implementations (e.g., Arithmetic, Logical, Comparison). These serve as reference examples for defining your own.

Implementation Patterns

• Custom Mutators: Implement MutatorInterface::mutate(mixed $value): iterable<mixed> to yield mutated variants. Mutations should be side-effect-free and deterministic.
• Composing Workflows: Use MutatorChain to stack mutators — each mutator operates on the original value unless explicitly chained as stateful (though the package favors stateless mutation).
• Pipeline Integration: Embed mutators into static analysis or testing pipelines: e.g., mutate expressions before running PHPUnit, or mutate node ASTs in your own PHPStan/Rector extensions.
• Targeted Mutation: Since mutators accept mixed, use type guards (is_string, is_numeric, etc.) to apply domain-specific mutations only to relevant inputs.

Gotchas and Tips

• Mutator Identity: Mutators must be pure — avoid dependencies on global state or randomness unless intended (e.g., via seeded RNG passed at runtime).
• Iteration Overhead: Each mutate() call yields an iterable, so use yield from inside mutator implementations to avoid nested arrays or nested generators.
• No Default Behavior: Unlike full frameworks (e.g., Infection core), this package does not parse code — you must integrate with AST or tokenizer separately and feed parsed values (e.g., AST node values) into mutators.
• Extensibility: To extend test coverage, write unit tests for your mutator via yield assertions — test edge cases like null, empty arrays, or float precision overflow.
• Performance: Mutators run sequentially per value — if composing many, benchmark deeply nested structures to ensure acceptable throughput.