PHP Fuzzer

https://github.com/nikic/php-fuzzer
Admin
PHP Fuzzer is a fuzzing tool that uses edge coverage instrumentation to find bugs in PHP libraries...
Tokens:49,631
Snippets:396
Trust Score:9.6
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### fuzz() usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Creates a `Fuzzer`, sets the corpus directory to a temporary path, and starts fuzzing.

```php
$fuzzer = new Fuzzer();
$fuzzer->setCorpusDir(sys_get_temp_dir() . '/corpus-123');
$fuzzer->fuzz();
```

--------------------------------

### RNG Usage Example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/RNG.md

Demonstrates usage of all RNG methods with example outputs.

```php
$rng = new RNG();
$rng->randomInt(10);        // 0..9
$rng->randomIntRange(5, 7); // 5..7
$rng->randomChar();         // one byte
$rng->randomPos("abc");     // 0, 1, or 2
$rng->randomPosOrEnd("abc");// 0..3
$rng->randomElement(['a', 'b']); // 'a' or 'b'
$rng->randomBool();         // true or false
$rng->randomString(4);      // 4 random bytes
```

--------------------------------

### addDictionary usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Shows how to add a dictionary file using a path relative to the current directory.

```php
$config->addDictionary(__DIR__ . '/php.dict');
```

--------------------------------

### Usage example of Context

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Context.md

Shows how to instantiate Context, bind fileInfo and code, and call getNewBlockIndex to allocate block indexes.

```php
use PhpFuzzer\Instrumentation\Context;
use PhpFuzzer\Instrumentation\FileInfo;
use PhpFuzzer\Instrumentation\MutableString;

$context = new Context('PhpFuzzer\\FuzzingContext');
$context->fileInfo = new FileInfo();
$context->code = new MutableString("<?php echo 1;");

$a = $context->getNewBlockIndex(6);  // int(1)
$b = $context->getNewBlockIndex(9);  // int(2)
print_r($context->fileInfo->blockIndexToPos); // [1 => 6, 2 => 9]
```

--------------------------------

### renderCoverage() usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Sets corpus and coverage directories, runs fuzzing, then renders the coverage report.

```php
$fuzzer->setCorpusDir('/tmp/corpus');
$fuzzer->setCoverageDir('/tmp/coverage');
$fuzzer->fuzz();
$fuzzer->renderCoverage();
```

--------------------------------

### setMaxLen usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Shows how to set the maximum input length to 1024 bytes.

```php
$config->setMaxLen(1024);
```

--------------------------------

### mutate() usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Mutator.md

Example of calling mutate() with a random mutation, e.g., change byte, insert, or erase. Requires an RNG and Dictionary instance.

```php
$rng = new RNG();
$mutator = new Mutator($rng, new Dictionary());
$out = $mutator->mutate("abc", 10, null);
// A random mutation, e.g. "abXc" (change byte), "abc" . "\xff" (insert), "bc" (erase), ...
```

--------------------------------

### setAllowedExceptions usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Shows how to ignore the library's own parse errors while keeping everything else as a bug. The example passes a single exception class.

```php
// Ignore the library's own parse errors, keep everything else as a bug.
$config->setAllowedExceptions([PhpParser\Error::class]);
```

--------------------------------

### Accepted dictionary format example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/DictionaryParser.md

Shows the dictionary file format accepted by the parser: one entry per line, either a bare quoted string or a name-value pair. Comments start with '#'. The example illustrates how escape sequences like \\, \", and \xHH are resolved, including NUL bytes materialized from \x00.

```text
# Comment
foo="bar"            -> "bar"
"baz"                -> "baz"
"\\abc\\abc\\"       -> "\abc\abc\"
"\"abc\"abc\""       -> "\"abc\"abc\""
"\x00abc\x00abc\x00" -> "\x00abc\x00abc\x00"   (NUL bytes materialized)
```

--------------------------------

### Usage example for registering Visitor in Instrumentor

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Visitor.md

Shows how to instantiate Context and Visitor, add the visitor to a NodeTraverser, and then traverse parsed statements. The context's code holds a MutableString after traversal.

```php
use PhpFuzzer\Instrumentation\Context;
use PhpFuzzer\Instrumentation\Visitor;

$context  = new Context('PhpFuzzer\\FuzzingContext');
$visitor  = new Visitor($context);
$ds       = new NodeTraverser();
$ds->addVisitor($visitor);
// ... then traverse parsed statements; $context->code holds a MutableString
```

--------------------------------

### addDictionary error handling example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Shows how to catch a FuzzerException when the dictionary file does not exist and write the error message to STDERR.

```php
try {
    $config->addDictionary('/non/existent.dict');
} catch (PhpFuzzer\FuzzerException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
}
```

--------------------------------

### Complete target usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

A complete target script that sets up a parser, defines the fuzzing target, sets max length, and adds a dictionary. Run with `php-fuzzer fuzz target.php corpus/`.

```php
<?php // target.php
/** @var PhpFuzzer\Config $config */

require 'vendor/autoload.php';

$parser = new Microsoft\PhpParser\Parser();
$config->setTarget(function(string $input) use($parser) {
    $parser->parseSourceFile($input);
});

$config->setMaxLen(1024);
$config->addDictionary('example/php.dict');
```

--------------------------------

### Target-side configuration example (target.php)

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/configuration.md

Configures a fuzzing target by setting the target closure, maximum input length, allowed exceptions, and a dictionary file. Must call setTarget() before fuzzing; $config is a PhpFuzzer\Config instance.

```php
<?php // target.php
/** @var PhpFuzzer\Config $config */
$config->setTarget(function(string $input) { /* exercise the library */ });
$config->setMaxLen(1024);
$config->setAllowedExceptions([MyLib\ParseError::class]);
$config->addDictionary(__DIR__ . '/php.dict');
```

--------------------------------

### MutableString usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Shows how to insert instrumentation around a function call using insert() with order values. The output demonstrates that edits are applied in order and the original string is preserved.

```php
use PhpFuzzer\Instrumentation\MutableString;

$s = new MutableString("if (\$a) { f(); }");
$s->insert(10, "{ trace(1); ", 0);
$s->insert(17, " }", 1);
echo $s->getModifiedString();
// if ($a) { { trace(1); f(); } }
```

--------------------------------

### handleCliArgs(): int

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Processes $_SERVER['argv'] via GetOpt, loads the target, installs timeout/error/shutdown handlers, and dispatches to the command handler. Returns the process exit code.

```APIDOC
## handleCliArgs(): int

### Description
Processes `$_SERVER['argv']` via GetOpt (ulrichsg/getopt-php), loads the target, installs the timeout/error/shutdown handlers, and dispatches to the command handler. Returns the process exit code (`0` success, `1` on argument errors or `FuzzerException`). This is the method invoked by `bin/php-fuzzer` (`exit($fuzzer->handleCliArgs());`).

### Method
handleCliArgs

### Parameters
None

### Returns
- `int` - Process exit code (`0` success, `1` on argument errors or `FuzzerException`).

### Example
```php
$fuzzer = new Fuzzer();
exit($fuzzer->handleCliArgs());
```
```

--------------------------------

### Example of traceBlock() wrapping a sub-expression

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzingContext.md

Shows how the instrumentation transforms a short-circuiting expression. The original if condition is rewritten to call traceBlock() with a block index, preserving the value of $bar.

```php
// Original:   if ($foo && $bar) { ... }
// Instrumented: if ($foo && \PhpFuzzer\FuzzingContext::traceBlock(42, $bar)) { ... }
```

--------------------------------

### FileInfo usage with Instrumentor

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/FileInfo.md

Shows how to create a FileInfo instance, instrument code with Instrumentor, and iterate the blockIndexToPos map to print each block's start position. The property is empty until a file is instrumented. Reusing one FileInfo for multiple files corrupts the mapping, so allocate a fresh instance per file.

```php
use PhpFuzzer\Instrumentation\FileInfo;
use PhpFuzzer\Instrumentation\Instrumentor;
use PhpParser\PhpVersion;

$info = new FileInfo();
$instrumentor = new Instrumentor('PhpFuzzer\\FuzzingContext', PhpVersion::getHostVersion());
$instrumentor->instrument("<?php if (\$a) { \$b; }", $info);

// Each instrumented block start is mapped:
foreach ($info->blockIndexToPos as $blockIndex => $pos) {
    printf("block %d starts at byte %d\n", $blockIndex, $pos);
}

```

--------------------------------

### setTarget usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Shows how to set a fuzzing target closure that parses input with a custom parser. The closure captures the parser and calls its parse method.

```php
/** @var PhpFuzzer\Config $config */
$parser = new MyParser();
$config->setTarget(function(string $input) use($parser) {
    $parser->parse($input);
});
```

--------------------------------

### setCorpusDir() usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Creates a `Fuzzer` instance and sets the corpus directory to `/tmp/seed-corpus`.

```php
$fuzzer = new Fuzzer();
$fuzzer->setCorpusDir('/tmp/seed-corpus');
```

--------------------------------

### Util::getCommonPathPrefix usage examples

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Util.md

Shows typical calls with expected return values. A single path is reduced to its parent directory; paths diverging at the first byte yield an empty string.

```php
use PhpFuzzer\Util;

Util::getCommonPathPrefix(['/foo/bar/abc.php', '/foo/bar/abd.php']);
// '/foo/bar/'

Util::getCommonPathPrefix(['/foo/abc/bar.php', '/foo/abd/bar.php']);
// '/foo/'

Util::getCommonPathPrefix([]);
// ''
```

--------------------------------

### Basic usage of DictionaryParser

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/DictionaryParser.md

Creates a parser instance and parses the contents of a dictionary file. The resulting words include examples like "<?", "<?php", "?>", "exit", "function", and "yield from".

```php
use PhpFuzzer\DictionaryParser;

$parser = new DictionaryParser();
$words  = $parser->parse(file_get_contents('example/php.dict'));

// Words include: "<?", "<?php", "?>", "exit", "function", "yield from", ...
```

--------------------------------

### Run fuzzer with and without initial corpus

Source: https://github.com/nikic/php-fuzzer/blob/master/README.md

Commands to start fuzzing. Without a corpus, a temporary corpus directory is created. With a corpus, provide one input per file. Fuzzing can be resumed later by specifying the same corpus directory.

```shell script
# Run without initial corpus
php-fuzzer fuzz target.php
# Run with initial corpus (one input per file)
php-fuzzer fuzz target.php corpus/
```

--------------------------------

### render(array $fileInfos, array $seenBlocks): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Generates the static HTML coverage report. Writes an index.html overview and one HTML file per instrumented file, highlighting covered and uncovered block starts.

```APIDOC
## render(array $fileInfos, array $seenBlocks): void

### Description
Generates a static HTML code-coverage report from instrumentation block maps. For each instrumented file it writes `<outDir>/<relative-path>.html` containing the source with each basic-block-start character highlighted green (covered) or red (not covered), plus an `index.html` overview table with per-file `numCovered/numTotal` counts.

### Method
render

### Parameters
- **$fileInfos** (`FileInfo[]`) - Required - Map of file path → `FileInfo` holding `blockIndexToPos` (block index → start position in the file).
- **$seenBlocks** (`array<int, bool>`) - Required - Set of block indexes executed at least once (from `Corpus::getSeenBlockMap()`).

### Returns
`void` - Side effects: creates `$outDir` with `@mkdir($this->outDir)` (silently ignoring failures), writes one HTML file per instrumented file plus `index.html`.

### Example
```php
$renderer = new CoverageRenderer('/tmp/coverage-report');
$renderer->render($fileInfos, $seenBlocks);
// Writes /tmp/coverage-report/index.html and one .html per instrumented file
```
```

--------------------------------

### handleCliArgs() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `handleCliArgs(): int` that processes CLI arguments via `GetOpt`, loads the target, installs handlers, and dispatches to the command handler. Returns exit code `0` on success, `1` on errors.

```php
public function handleCliArgs(): int
```

--------------------------------

### Corpus usage example

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Corpus.md

Shows how to construct a Corpus, compute unique features for an entry, add it, and check corpus stats and crash deduplication. The first addCrashEntry call returns true because feature 123 is new; the second returns false as a duplicate crash.

```php
$corpus = new Corpus();
$entry  = new CorpusEntry("input", [123 => true], (string) new Error('boom'));
$corpus->computeUniqueFeatures($entry);
$corpus->addEntry($entry);                    // input considered interesting
var_dump($corpus->getNumCorpusEntries());     // int(1)
var_dump($corpus->getNumFeatures());          // int(1)
var_dump($corpus->addCrashEntry($entry));     // bool(true)  — first sight of feature 123
var_dump($corpus->addCrashEntry($entry));     // bool(false) — duplicate crash
```

--------------------------------

### Catching FuzzerException in consumer code

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzerException.md

Example of catching FuzzerException when calling library methods that may throw it, such as setCorpusDir(). This demonstrates how to handle configuration errors in consumer code.

```APIDOC
## [USAGE] Catching FuzzerException

### Description
Example of catching FuzzerException when calling library methods that may throw it, such as setCorpusDir(). This demonstrates how to handle configuration errors in consumer code.

### Code Example
```php
use PhpFuzzer\Fuzzer;
use PhpFuzzer\FuzzerException;

$fuzzer = new Fuzzer();
try {
    $fuzzer->setCorpusDir('/no/such/corpus');
} catch (FuzzerException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL); // Corpus directory "/no/such/corpus" does not exist
    exit(1);
}
```
```

--------------------------------

### Programmatic driver mirroring bin/php-fuzzer error handling

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzerException.md

Example of a programmatic driver that mirrors the error handling of the bin/php-fuzzer CLI, catching FuzzerException and exiting with code 1.

```APIDOC
## [USAGE] Programmatic driver

### Description
Example of a programmatic driver that mirrors the error handling of the bin/php-fuzzer CLI, catching FuzzerException and exiting with code 1.

### Code Example
```php
// Programmatic driver mirroring bin/php-fuzzer error handling
try {
    $fuzzer = new Fuzzer();
    $fuzzer->setCorpusDir($corpus);
    $fuzzer->fuzz();
} catch (PhpFuzzer\FuzzerException $e) {
    echo $e->getMessage() . PHP_EOL;
    exit(1);
}
```
```

--------------------------------

### Instrumentation for basic blocks inside expressions

Source: https://github.com/nikic/php-fuzzer/blob/master/README.md

When a basic block is part of an expression, a call to traceBlock is inserted instead of the full instrumentation code. The example shows how `if ($foo && $bar)` becomes `if ($foo && \PhpFuzzer\FuzzingContext::traceBlock(BLOCK_INDEX, $bar))`. This is used when additional code cannot be easily inserted directly.

```php
if ($foo && $bar) { ... }
// becomes
if ($foo && \PhpFuzzer\FuzzingContext::traceBlock(BLOCK_INDEX, $bar)) { ... }
```

--------------------------------

### Define target function for tolerant-php-parser

Source: https://github.com/nikic/php-fuzzer/blob/master/README.md

Required setup for fuzzing a library: define a target that accepts a single input string and runs it through the tested library. Normal Exceptions are ignored, but Error exceptions are considered bugs. Optional configurations include setMaxLen(1024) to limit input length and addDictionary() to provide useful fragments like language keywords.

```php
<?php // target.php

/** @var PhpFuzzer\Config $config */

require 'path/to/tolerant-php-parser/vendor/autoload.php';

// Required: The target accepts a single input string and runs it through the tested
//           library. The target is allowed to throw normal Exceptions (which are ignored),
//           but Error exceptions are considered as a found bug.
$parser = new Microsoft\PhpParser\Parser();
$config->setTarget(function(string $input) use($parser) {
    $parser->parseSourceFile($input);
});

// Optional: Many targets don't exhibit bugs on large inputs that can't also be
//           produced with small inputs. Limiting the length may improve performance.
$config->setMaxLen(1024);
// Optional: A dictionary can be used to provide useful fragments to the fuzzer,
//           such as language keywords. This is particularly important if these
//           cannot be easily discovered by the fuzzer, because they are handled
//           by a non-instrumented PHP extension function such as token_get_all().
$config->addDictionary('example/php.dict');
```

--------------------------------

### Generated inline block stub code

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Visitor.md

Probe code inserted at block starts. Uses BLOCK_INDEX from context and updates edge counters and previous block tracking in FuzzingContext.

```php
$___key = (\PhpFuzzer\FuzzingContext::$prevBlock << 28) | BLOCK_INDEX;
\PhpFuzzer\FuzzingContext::$edges[$___key] = (\PhpFuzzer\FuzzingContext::$edges[$___key] ?? 0) + 1;
\PhpFuzzer\FuzzingContext::$prevBlock = BLOCK_INDEX;
```

--------------------------------

### startInstrumentation(): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Calls Interceptor::setUp() so that all subsequently included PHP files (outside src/) are rewritten with coverage probes. Must be called before loading the target script.

```APIDOC
## startInstrumentation(): void

### Description
Calls Interceptor::setUp() so that all subsequently included PHP files (outside src/) are rewritten with coverage probes. Must be called before loading the target script.

### Method
startInstrumentation

### Parameters
None

### Example
```php
$fuzzer->startInstrumentation();
```
```

--------------------------------

### startInstrumentation() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `startInstrumentation(): void` that calls `Interceptor::setUp()` to rewrite subsequently included PHP files with coverage probes. Must be called before loading the target script.

```php
public function startInstrumentation(): void
```

--------------------------------

### Typical usage of CoverageRenderer

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Shows how to instantiate CoverageRenderer and call render to generate coverage report files.

```php
$renderer = new CoverageRenderer('/tmp/coverage-report');
$renderer->render($fileInfos, $seenBlocks);
// Writes /tmp/coverage-report/index.html and one .html per instrumented file
```

--------------------------------

### Constructor signature for Visitor

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Visitor.md

Constructor that accepts a shared Context object holding instrumentation state such as runtimeContextName, FileInfo out-map, and the MutableString being edited.

```php
public function __construct(Context $context)
```

--------------------------------

### new CoverageRenderer(string $outDir)

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Constructor for the CoverageRenderer class. Initializes the renderer with the output directory where the coverage report files will be written.

```APIDOC
## Constructor

### Description
Creates a new CoverageRenderer instance.

### Signature
```php
public function __construct(string $outDir)
```

### Parameters
- **$outDir** (string) - Required - Directory where the report files (`index.html`, per-file `.html`) are written.

### Example
```php
$renderer = new CoverageRenderer('/tmp/coverage-report');
```
```

--------------------------------

### leaveNode method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Visitor.md

Overrides NodeVisitorAbstract::leaveNode(). Returns null in all paths and dispatches purely on node type without rewriting the AST.

```php
public function leaveNode(Node $node)
```

--------------------------------

### Creating a CorpusEntry and accessing its hash

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CorpusEntry.md

Shows how to instantiate a CorpusEntry with a sample input and feature set, then access the hash property which is the MD5 of the input.

```php
$entry = new CorpusEntry("<?php echo 1;", [123456 => true], null);
echo $entry->hash; // md5 of the input
```

--------------------------------

### Basic usage of Instrumentor::instrument

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Instrumentor.md

Shows how to instantiate Instrumentor and instrument a simple PHP function. The resulting $instrumented contains probe code and $fileInfo->blockIndexToPos maps block indexes to positions.

```php
use PhpFuzzer\Instrumentation\FileInfo;
use PhpFuzzer\Instrumentation\Instrumentor;
use PhpParser\PhpVersion;

$instrumentor = new Instrumentor('PhpFuzzer\\FuzzingContext', PhpVersion::getHostVersion());
$fileInfo = new FileInfo();
$code = <<<'PHP'
<?php
function test($x) {
    if ($x) {
        return 1;
    }
    return 0;
}
PHP;
$instrumented = $instrumentor->instrument($code, $fileInfo);
// $instrumented contains the generated $___key = (...) << 28 | N; ... probes
// $fileInfo->blockIndexToPos maps each block index N to its position in $code
```

--------------------------------

### CoverageRenderer render method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Renders coverage report from file infos and seen blocks. Creates output directory and writes HTML files.

```php
/**
 * @param FileInfo[] $fileInfos
 * @param array<int, bool> $seenBlocks
 */
public function render(array $fileInfos, array $seenBlocks): void
```

--------------------------------

### Catching FuzzerException in consumer code

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzerException.md

Example of catching a FuzzerException when setting a corpus directory. The exception is caught and printed to STDERR with exit code 1. Note that inside fuzzing targets, Config::$allowedExceptions defaults to [\Exception::class], so a FuzzerException thrown by the target would be treated as a normal (non-crashing) result.

```php
use PhpFuzzer\Fuzzer;
use PhpFuzzer\FuzzerException;

$fuzzer = new Fuzzer();
try {
    $fuzzer->setCorpusDir('/no/such/corpus');
} catch (FuzzerException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL); // Corpus directory "/no/such/corpus" does not exist
    exit(1);
}
```

--------------------------------

### Run single input to check exception trace

Source: https://github.com/nikic/php-fuzzer/blob/master/README.md

Quickly check the exception trace produced for a crashing input using the run-single command.

```shell script
php-fuzzer run-single target.php minimized-HASH.txt
```

--------------------------------

### Context constructor signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Context.md

Constructor for the Context class, accepting the runtime context class name.

```php
public function __construct(string $runtimeContextName)
```

--------------------------------

### storeAtPath method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CorpusEntry.md

Declares the method that writes the input verbatim to the given path via file_put_contents() and records the path. Asserts that the entry hasn't been stored before and that the full input was written.

```php
public function storeAtPath(string $path): void
```

--------------------------------

### $dictionary (public property)

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/configuration.md

Direct word-list access. Allows adding words directly to the dictionary.

```APIDOC
## $dictionary (public property)

### Description
Direct word-list access. Allows adding words directly to the dictionary.

### Property
$dictionary

### Type
Dictionary

### Example
```php
$config->dictionary->addWords([...]);
```
```

--------------------------------

### storeAtPath(string $path): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CorpusEntry.md

Writes the entry's input verbatim to the specified filesystem path and records the path. The method asserts that the entry has not been stored before and that the full input was written.

```APIDOC
## Method: storeAtPath

### Description
Writes `$this->input` verbatim to `$path` via `file_put_contents()` and records the path. Two `assert()`ions guard preconditions: the entry must not have been stored before, and the full input must have been written. With assertions disabled (production), a repeated call simply overwrites the file and updates `path`.

### Signature
```php
public function storeAtPath(string $path): void
```

### Parameters
- **$path** (string) - Required - The filesystem path where the input should be stored.

### Example
```php
$entry = new CorpusEntry($input, $features, null);
$entry->storeAtPath('/tmp/corpus/' . $entry->hash . '.txt');
echo $entry->path; // /tmp/corpus/<md5>.txt
```

### Notes
- Crash entries are stored by `Fuzzer::fuzz()` as `crash-<hash>.txt` in the output directory.
- Corpus entries are stored as `<hash>.txt` in the corpus directory.
- Minimized inputs are stored as `minimized-<md5(input)>.txt` in `getcwd()`.
- Shutdown-fatal crash entries are stored as `crash-<hash>.txt`.

### Error Handling
A failure to write surfaces as a standard PHP warning (`file_put_contents()` return value is only asserted, so with `zend.assertions=0` a failed write goes unnoticed besides the warning). Use the fuzzer-side `FuzzerException` checks — e.g. `setCorpusDir()` — to validate directories up front rather than relying on this method.
```

--------------------------------

### CoverageRenderer constructor signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Constructor for CoverageRenderer that takes an output directory where report files are written.

```php
public function __construct(string $outDir)
```

--------------------------------

### getNewBlockIndex method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Context.md

Method signature for allocating a new block index.

```php
public function getNewBlockIndex(int $pos): int
```

--------------------------------

### fuzz(): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Runs the main fuzzing loop until $maxRuns is reached (PHP_INT_MAX by default, i.e. until aborted). Must be preceded by setCorpusDir().

```APIDOC
## fuzz(): void

### Description
Runs the main fuzzing loop until $maxRuns is reached (PHP_INT_MAX by default, i.e. until aborted). Must be preceded by setCorpusDir().

### Method
fuzz

### Parameters
None

### Behavior
- Picks a random corpus entry and a second random entry for crossover; empty corpus yields `""` / `null`.
- Applies up to `mutationDepthLimit` (default 5) mutations via `Mutator::mutate($input, $maxLen, $crossOverInput)`.
- Runs the target and handles crashes, new features, and reductions.
- Automatic length control: while `$maxLen < $this->config->maxLen`, if no action happened in the last `lenControlFactor * log2($maxLen)` runs, `$maxLen` is increased by `log2($maxLen)` bytes (capped at `Config::$maxLen`).

### Throws
- `PhpFuzzer\FuzzerException` if the corpus directory does not exist (via private `loadCorpus()`).

### Example
```php
$fuzzer = new Fuzzer();
$fuzzer->setCorpusDir(sys_get_temp_dir() . '/corpus-123');
$fuzzer->fuzz();
```
```

--------------------------------

### Constructor: __construct(string $string)

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Creates a new MutableString instance with the original source text to edit.

```APIDOC
## Constructor: __construct(string $string)

### Description
Creates a new MutableString instance with the original source text to edit.

### Method
__construct

### Signature
```php
public function __construct(string $string)
```

### Parameters
- **$string** (string) - Required - The original source text to edit.

```

--------------------------------

### renderCoverage(): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Renders an HTML coverage report into the configured coverage directory using CoverageRenderer::render(). Throws FuzzerException if setCoverageDir() was not called.

```APIDOC
## renderCoverage(): void

### Description
Renders an HTML coverage report into the configured coverage directory using CoverageRenderer::render() with the collected FileInfo map and the corpus getSeenBlockMap(). Throws FuzzerException if setCoverageDir() was not called.

### Method
renderCoverage

### Parameters
None

### Throws
- `PhpFuzzer\FuzzerException` with message `Missing coverage directory` if `setCoverageDir()` was not called.

### Prerequisites
- Must be preceded by corpus loading (fuzzing or `report-coverage` command) so that block maps are populated.

### Example
```php
$fuzzer->setCorpusDir('/tmp/corpus');
$fuzzer->setCoverageDir('/tmp/coverage');
$fuzzer->fuzz();
$fuzzer->renderCoverage();
```
```

--------------------------------

### Instrumentor constructor signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Instrumentor.md

Creates an Instrumentor with a runtime context class name and PHP version. The Fuzzer passes FuzzingContext::class and PhpVersion::getHostVersion().

```php
public function __construct(string $runtimeContextName, PhpVersion $phpVersion)
```

--------------------------------

### Using Dictionary with Mutator

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Dictionary.md

Creates a Dictionary, adds words, and feeds it to a Mutator. The mutate() call may now produce output containing dictionary words.

```php
use PhpFuzzer\Mutation\Dictionary;
use PhpFuzzer\Mutation\RNG;

$dictionary = new Dictionary();
$dictionary->addWords(['function', 'return', '<?php']);

// Feed it to a mutator:
$mutator = new Mutator(new RNG(), $dictionary);
$out = $mutator->mutate('foo', 32, null); // may now contain dictionary words
```

--------------------------------

### renderCoverage() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `renderCoverage(): void` that renders an HTML coverage report using `CoverageRenderer::render()`. Throws `PhpFuzzer\FuzzerException` with message `Missing coverage directory` if `setCoverageDir()` was not called.

```php
public function renderCoverage(): void
```

--------------------------------

### addDictionary(string $path): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Parses a libFuzzer-style dictionary file with DictionaryParser and appends the words to $this->dictionary. Throws PhpFuzzer\FuzzerException with message `Dictionary "<path>" does not exist` if the file is missing; propagates \Exception from DictionaryParser::parse() for malformed lines.

```APIDOC
## addDictionary(string $path): void

### Description
Parses a libFuzzer-style dictionary file with `DictionaryParser` and appends the words to `$this->dictionary`. **Throws** `PhpFuzzer\FuzzerException` with message `Dictionary "<path>" does not exist` if the file is missing; propagates `\Exception` from `DictionaryParser::parse()` for malformed lines.

### Method
addDictionary

### Parameters
- **$path** (string) - Required - Path to the dictionary file.

### Request Example
```php
$config->addDictionary(__DIR__ . '/php.dict');
```

### Response
#### Success Response
No return value (void).

#### Error Handling
- **PhpFuzzer\FuzzerException** - Thrown if the dictionary file does not exist.
- **\Exception** - Propagated from `DictionaryParser::parse()` for malformed lines.

### Error Example
```php
try {
    $config->addDictionary('/non/existent.dict');
} catch (PhpFuzzer\FuzzerException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
}
```
```

--------------------------------

### CLI usage of report-coverage command

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CoverageRenderer.md

Command-line invocation to generate coverage report using the report-coverage command.

```shell
php-fuzzer report-coverage target.php corpus/ coverage_dir/
```

--------------------------------

### isEmpty method

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Dictionary.md

Returns true when the dictionary is empty. Consulted by mutateAddWordFromManualDictionary() before using the dictionary; when empty, that mutator returns null.

```php
public function isEmpty(): bool
```

--------------------------------

### insert(int $pos, string $newString, int $order = 0): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Convenience wrapper for replace() that inserts newString before the given offset.

```APIDOC
## insert(int $pos, string $newString, int $order = 0): void

### Description
Convenience wrapper for replace() that inserts newString before the given offset.

### Method
insert

### Signature
```php
public function insert(int $pos, string $newString, int $order = 0): void
```

### Parameters
- **$pos** (int) - Required - Offset in the original string where the insertion occurs.
- **$newString** (string) - Required - Text to insert.
- **$order** (int) - Optional (default 0) - Tie-breaker for edits at the same position.

```

--------------------------------

### Instrumentor::__construct(string $runtimeContextName, PhpVersion $phpVersion)

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Instrumentor.md

Creates an Instrumentor instance that parses and rewrites PHP source code to insert coverage probes. The runtime context name and PHP version are used to configure the parser and probe generation.

```APIDOC
## Constructor

### Description
Creates an Instrumentor instance that parses and rewrites PHP source code to insert coverage probes.

### Method
Constructor

### Signature
`public function __construct(string $runtimeContextName, PhpVersion $phpVersion)`

### Parameters
- **$runtimeContextName** (string) - Required - Fully-qualified class name of the runtime context; probes reference `\$runtimeContextName::$prevBlock` / `::$edges` / `::traceBlock()`. The `Fuzzer` passes `FuzzingContext::class`.
- **$phpVersion** (`PhpParser\PhpVersion`) - Required - PHP version used to select the parser; the `Fuzzer` passes `PhpVersion::getHostVersion()`.

### Notes
Setup creates a parser, a NodeTraverser, a Context for block-index bookkeeping, and registers a Visitor on the traverser.
```

--------------------------------

### Dictionary constructor

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Dictionary.md

Implicit constructor; the dict property is initialized to an empty array.

```php
public function __construct()
```

--------------------------------

### Compare two parser implementations with setTarget

Source: https://github.com/nikic/php-fuzzer/blob/master/README.md

Use this target to detect output mismatches between two implementations. Throws an Error when results differ, which the fuzzer treats as a failure. The fuzzer considers uncaught Error exceptions as programming errors, while Exception exceptions are normal for malformed input.

```php
$fuzzer->setTarget(function(string $input) use($parser1, $parser2) {
    $result1 = $parser1->parse($input);
    $result2 = $parser2->parse($input);
    if ($result1 != $result2) {
        throw new Error('Results do not match!');
    }
});
```

--------------------------------

### Safe Random Position Helper

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/RNG.md

Robust position helper for consumer code that avoids \Error from randomPos() on empty strings.

```php
// Robust position helper for consumer code
function safeRandomPos(RNG $rng, string $str): ?int {
    if ($str === '') {
        return null; // avoid \Error from randomPos()
    }
    return $rng->randomPos($str);
}
```

--------------------------------

### setCoverageDir(string $path): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Sets the output directory for the HTML coverage report. May be called before renderCoverage(). No validation is performed here.

```APIDOC
## setCoverageDir(string $path): void

### Description
Sets the output directory for the HTML coverage report. May be called before renderCoverage(). No validation is performed here.

### Method
setCoverageDir

### Parameters
- `$path` (string) - Required - Path to the output directory for the HTML coverage report.

### Example
```php
$fuzzer->setCoverageDir('/tmp/coverage');
```
```

--------------------------------

### addWords method with docblock

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Dictionary.md

Appends words to the dictionary via array spread. Duplicate words are not deduplicated.

```php
/**
 * @param list<string> $words
 */
public function addWords(array $words): void
```

--------------------------------

### traceBlock() method signature with docblock

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzingContext.md

Records an edge and returns the passed value unchanged, allowing instrumentation to wrap sub-expressions without altering their value. The @template T docblock indicates the return type matches the input type.

```php
/**
 * @template T
 * @param int $blockIndex
 * @param T $returnValue
 * @return T
 */
public static function traceBlock($blockIndex, $returnValue)
```

--------------------------------

### fuzz() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `fuzz(): void` that runs the main fuzzing loop until `$maxRuns` is reached (default `PHP_INT_MAX`). Must be preceded by `setCorpusDir()`; otherwise `loadCorpus()` throws `FuzzerException`.

```php
public function fuzz(): void
```

--------------------------------

### setCoverageDir() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `setCoverageDir(string $path): void` that sets the output directory for the HTML coverage report. May be called before `renderCoverage()`; no validation is performed.

```php
public function setCoverageDir(string $path): void
```

--------------------------------

### addDictionary method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Declares the addDictionary method that parses a libFuzzer-style dictionary file and appends words to the dictionary. Throws FuzzerException if the file is missing.

```php
public function addDictionary(string $path): void
```

--------------------------------

### setMaxLen method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Declares the setMaxLen method that sets the absolute maximum input length in bytes. Limiting length can improve performance.

```php
public function setMaxLen(int $maxLen): void
```

--------------------------------

### MutableString constructor

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Creates a MutableString instance with the original source text to edit. Offsets into the original string remain valid after edits.

```php
public function __construct(string $string)
```

--------------------------------

### Adding words via public Config dictionary

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Dictionary.md

Because Config::$dictionary is public, a target script can add words directly to the dictionary in place.

```php
/** @var PhpFuzzer\Config $config */
$config->dictionary->addWords(['my-custom-token']);
```

--------------------------------

### getOrigString(): string

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Returns the unmodified original string.

```APIDOC
## getOrigString(): string

### Description
Returns the unmodified original string.

### Method
getOrigString

### Signature
```php
public function getOrigString(): string
```

### Returns
- **string** - The original string as passed to the constructor.

```

--------------------------------

### randomElement Method

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/RNG.md

Returns one element of $array with uniform probability. Assumes a list (dense 0..n-1 keys) and throws \Error (undefined array key) for associative arrays or an empty array (randomInt(0) → invalid mt_rand range).

```php
/**
 * @template T
 * @param list<T> $array
 * @return T
 */
public function randomElement(array $array)
```

--------------------------------

### Storing a CorpusEntry at a path

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CorpusEntry.md

Shows how to store a CorpusEntry to a file path and then access the path property, which is set to the provided path after storage.

```php
$entry = new CorpusEntry($input, $features, null);
$entry->storeAtPath('/tmp/corpus/' . $entry->hash . '.txt');
echo $entry->path; // /tmp/corpus/<md5>.txt
```

--------------------------------

### Exception::__construct

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/FuzzerException.md

Inherited constructor for FuzzerException. It is used to create an exception instance with an optional message, code, and previous throwable. All arguments are optional and the library itself only passes the message argument.

```APIDOC
## [CONSTRUCTOR] Exception::__construct

### Description
Inherited constructor for FuzzerException. It is used to create an exception instance with an optional message, code, and previous throwable. All arguments are optional and the library itself only passes the message argument.

### Method
__construct

### Signature
```php
public Exception::__construct(string $message = "", int $code = 0, ?Throwable $previous = null)
```

### Parameters
- **message** (string) - Optional - The exception message.
- **code** (int) - Optional - The exception code.
- **previous** (?Throwable) - Optional - The previous throwable used for exception chaining.

### Usage Example
```php
use PhpFuzzer\FuzzerException;

$e = new FuzzerException('Configuration error');
```
```

--------------------------------

### randomPosOrEnd Method

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/RNG.md

Returns a random index in [0, strlen($str)] — the empty string is valid here and returns 0.

```php
public function randomPosOrEnd(string $str): int
```

--------------------------------

### setTarget method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Declares the setTarget method that accepts a closure. The closure receives a single string input and is allowed to throw exceptions; Errors are considered bugs.

```php
public function setTarget(\Closure $target): void
```

--------------------------------

### Instrumentor::instrument method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/Instrumentor.md

Instruments PHP source code, filling $fileInfo with blockIndexToPos mapping. Returns instrumented source with preserved positions.

```php
public function instrument(string $code, FileInfo $fileInfo): string
```

--------------------------------

### setCorpusDir() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Fuzzer.md

Declares the public method `setCorpusDir(string $path): void` that sets the directory containing seed inputs. Throws `PhpFuzzer\FuzzerException` if the directory does not exist.

```php
public function setCorpusDir(string $path): void
```

--------------------------------

### parse() method signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/DictionaryParser.md

Declares the public parse method that accepts the full dictionary file contents and returns a list of parsed words with escape sequences resolved. The method throws an \Exception for invalid lines.

```php
/**
 * @return list<string>
 */
public function parse(string $code): array
```

--------------------------------

### Check every mutator's length contract with deterministic RNG

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/Mutator.md

Iterates over all mutators from `getMutators()`, applying each to a random 50-character string with a random max length up to 100. Throws a RuntimeException if any mutator returns a non-null result longer than 100, verifying the length contract under `zend.assertions=1`.

```php
// Deterministic-style structural check of every mutator's length contract
$rng = new RNG();
$mutator = new Mutator($rng, new Dictionary());
foreach ($mutator->getMutators() as $name => $fn) {
    for ($i = 0; $i < 100; $i++) {
        $result = $fn($rng->randomString(50), $rng->randomInt(100));
        if ($result !== null && strlen($result) > 100) {
            throw new RuntimeException("$name violated maxLen");
        }
    }
}
```

--------------------------------

### MutableString::insert method

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Instrumentation/MutableString.md

Convenience wrapper for replace() that inserts $newString before offset $pos (equivalent to replace($pos, 0, $newString, $order)).

```php
public function insert(int $pos, string $newString, int $order = 0): void
```

--------------------------------

### randomString Method

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Mutation/RNG.md

Returns a string of $len random bytes (concatenates $len randomChar() results).

```php
public function randomString(int $len): string
```

--------------------------------

### setAllowedExceptions(array $allowedExceptions): void

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Config.md

Replaces the list of \Throwable classes (full class names) that are treated as normal results of malformed input rather than crashes. Defaults to [\Exception::class], i.e. every Error subclass counts as a bug.

```APIDOC
## setAllowedExceptions(array $allowedExceptions): void

### Description
Replaces the list of `\Throwable` classes (full class names) that are treated as normal results of malformed input rather than crashes. Defaults to `[\Exception::class]`, i.e. every `Error` subclass counts as a bug. The check is `$e instanceof $allowedException`.

### Method
setAllowedExceptions

### Parameters
- **$allowedExceptions** (list<class-string<\Throwable>>) - Required - Exception class names to ignore.

### Request Example
```php
// Ignore the library's own parse errors, keep everything else as a bug.
$config->setAllowedExceptions([PhpParser\Error::class]);
```

### Response
#### Success Response
No return value (void).
```

--------------------------------

### CorpusEntry constructor signature

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/CorpusEntry.md

Declares the constructor for CorpusEntry, which takes the input string, a feature set keyed by feature integer (values must be true), and an optional crash description. The hash property is set to md5($input) in the constructor.

```php
/**
 * @param array<int, bool> $features
 */
public function __construct(string $input, array $features, ?string $crashInfo)
```

--------------------------------

### CoverageRenderer usage of Util::getCommonPathPrefix

Source: https://github.com/nikic/php-fuzzer/blob/master/_autodocs/api-reference/Util.md

In-tree caller that strips the common prefix from instrumented file paths and writes rendered HTML files under the output directory. Uses @mkdir to suppress warnings and file_put_contents to write the result.

```php
// src/CoverageRenderer.php:41-50 (abridged)
$prefix = Util::getCommonPathPrefix(array_keys($fileInfos));
foreach ($fileInfos as $path => $fileInfo) {
    $shortPath = str_replace($prefix, '', $path);
    $outPath = $this->outDir . '/' . $shortPath . '.html';
    @mkdir(dirname($outPath), 0777, true);
    file_put_contents($outPath, $result);
}
```
Tokens:
Raw