doc-exec — doctest for PHP. Executes README code blocks against the current code and diffs the output
$ composer require --dev rasuvaeff/doc-exec
```php doc-exec
2 + 3; // => 5
intdiv(1, 0); // throws DivisionByZeroError
echo "done"; // outputs done
network_call(); // skip: hits a real API
```vendor/bin/doc-exec docs/*.md
vendor/bin/doc-exec --bootstrap=tests/bootstrap.php README.mdDoctest for PHP: execute the code blocks in your README against the current codebase and diff the result. It does for PHP what cargo test --doc does for Rust.
Documentation examples rot. The API changes and the README keeps showing code that no longer runs. Here the sample is a test, so the build fails when it breaks.
php doc-exec info string run. Plain php blocks stay illustrative.// => expr, // throws FQCN, // outputs text, // skip.nikic/php-parser), not by pattern matching.php process. No eval().--timeout per scope group (30 s by default) kills blocks that loop forever.DocExec::check() returns a DocumentResult with stable block ids.vendor/bin/doc-exec checks ./README.md.Trailing marker comments assert a value, an exception, printed output, or skip a statement.
2 + 3;=> 5intdiv(1, 0);throws DivisionByZeroErrorecho "done";outputs donenetwork_call();skip: hits a real API
CLI usage: check the README by default, or pass files, a bootstrap and a timeout; exit code 1 on failure.
vendor/bin/doc-exec # zero-config: checks ./README.md
vendor/bin/doc-exec docs/*.md # explicit file list
vendor/bin/doc-exec --bootstrap=tests/bootstrap.php README.md # explicit autoloader
vendor/bin/doc-exec --timeout=60 docs/slow.md # wall-clock budget per scope groupThe DocExec API returns per-statement results instead of a console report.
$result = (new DocExec(timeoutSeconds: 15))->check($document); printf("%s: %s\n", basename($document), $result->passed() ? 'all blocks passed' : 'some blocks failed'); foreach ($result->blocks as $block) { foreach ($block->statements as $statement) { printf( " %-4s line %d %s\n", match ($statement->outcome) { StatementOutcome::Pass => 'pass', StatementOutcome::Skip => 'skip', StatementOutcome::Fail => 'FAIL', }, $statement->statement->line, strtok($statement->statement->code, "\n"), ); }}
The resilience README sample is executed on every build through it.
Blocks run arbitrary PHP with the caller's permissions. The timeout bounds time only, not memory or filesystem access. It is 0.1.0.
Requires PHP 8.3–8.5, ext-tokenizer and nikic/php-parser ^5.7.
/ search · n N next, previous · g G top, bottom · q back to the index