Repository navigation
First release.
- Executes
php doc-execfenced code blocks from Markdown against the current
codebase, in a childphpprocess — nevereval(), never in-process. - Markers on a statement's trailing comment:
// => <expr>,
// throws <FQCN>[ | <substring>],// outputs <text>,// skip[: <reason>]. - Blocks under one Markdown heading share a variable scope, in document order.
- Blocks are split into statements by
nikic/php-parser, so closures,
if/else,try/catch,match, anonymous classes anddo/whileare
each one statement. - A block that is not valid PHP fails on its own, with the line inside the
block; the other blocks of its scope group still run. - Each scope group runs under a wall-clock deadline (30 s by default,
--timeout=<seconds>), so a runaway example fails the build instead of
wedging it. - CLI:
vendor/bin/doc-exec [--bootstrap=<file>] [--timeout=<seconds>] [--help] [file.md ...], defaulting to./README.md. Exit0all passed,1a block
failed,2a usage error. - Runs on Windows as well as POSIX systems: the child process communicates
entirely through files rather than pipes, so neither the unreachable file
descriptor 3 norstream_select()'s behaviour on Windows pipes applies.
Documents are read the same whether they are saved with LF, CRLF or CR line
endings. useandconstdeclarations inside a block are emitted at file level,
where PHP accepts them; a document's owndeclare(strict_types=…)is
dropped, since the generated script declares its own first.- A marker keyword with no payload —
// =>,// throws,// outputs—
fails the statement with a diagnostic instead of silently reading as prose. - Programmatic API:
DocExec::check()returningDocumentResult→
BlockResult→StatementResult, plusStableIdfor tracking a block
across edits elsewhere in the document.