Runnable code examples in the Laravel documentation

[mho22]

I built a proof of concept where every PHP code block in the 13.x documentation runs directly in the browser: : Laravel Snippets. The laravel/docs markdown sources sync daily, so it tracks the official docs.

A side effect turned out to be valuable on its own : a weekly sweep runs every snippet through Playwright and records which ones complete : The report. That sweep surfaced the 50 syntax errors fixed in laravel/docs#11364.

Proposal

Would there be interest in bringing either of these to the official documentation?

1. A "Run" button on PHP code blocks. The runner is a self-contained web worker plus a static Laravel bundle, and it attaches to already-rendered code blocks:

code block → web worker [ PHP 8.5 via @php-wasm/web ] → output rendered inline

2. Snippet validation. Even without any UI, the sweep catches broken examples before readers do, and it can report failures per page and per snippet.

Since laravel.com is closed source, I can't contribute this as a PR. I'd be glad to help integrate it, extract the runner as a package, or adapt whichever part is useful.

[shaedrich]

It would make sense to run these right in the pipeline to prevent new syntax error being merged into the master

[vynazevedo]

The CI validation part looks useful independently of the Run button. I would make the unit of validation an explicitly classified example, though, rather than treating every PHP fence as a standalone program.

Laravel docs contain complete programs, method bodies, configuration fragments, diffs and examples whose variables were introduced in the surrounding text. A failure report needs to distinguish invalid PHP from “requires a fixture/context” and from “valid example but unsupported by the browser runtime.” Otherwise maintainers can end up rewriting good explanatory fragments just to satisfy the runner.

A useful first CI contract would record the docs commit, page/heading, stable snippet identifier, PHP/framework versions, fixture and expected outcome. Start with changed snippets, allow intentional expected failures, and report infrastructure failures separately from example failures. Two adjacent examples should not accidentally share database or static state unless they are explicitly one scenario.

For the browser runner, I would additionally bound execution time and output, isolate runs, and make required extensions/network services visible before execution. A code block that demonstrates queues or an external database should not show a green “works” solely because a stub let it parse.

I haven't run the linked PoC or rechecked the reported 50 fixes; these are proposed acceptance criteria for moving its validation into official CI. An initial opt-in set of complete examples would make false-positive rates measurable before expanding coverage.

[shaedrich]

For database examples, a query listener could show executed queries against the fixture database. I would start counting after setup and label the database driver, since an SQLite run does not validate behavior specific to MySQL or PostgreSQL.

That's an important point: There are a lot of configuration options. One would either have to set them programmatically, which would keep it readable but would probably not correctly reflect most use cases or we would need some kind of setup UI:

----
config:
    app:
        locale: en-GB
    database:
        driver: sqlite
    queue:
        driver: sync
----
<?php
MyJob::dispatch();

rendered as:

| db: SQLite ▼ | queue: sync ▼ | locale: en-GB ▼ |
┕--------------┴---------------┴-----------------┘

<?php
MyJob::dispatch();

┌---------┬----------┬------------┐
| mail: 0 | queue: 1 | queries: 0 |

[vynazevedo]

@shaedrich A small setup UI seems workable. I would let each example declare its supported choices, then use that same declaration for the controls and CI. That avoids offering combinations the browser runtime cannot actually execute.

One implementation detail if that front matter is meant as runner metadata rather than literal Laravel configuration. The selected connection names map to database.default and queue.default; each connection then has its own driver and options under connections. The database config and queue config show the distinction. A simplified UI schema can still work, provided the translation is explicit.

I would also keep the execution mode separate from the connection selector. With a queue fake, the panel counts captured jobs. With the actual sync connection and no fake intercepting dispatch, jobs execute in the current process, so their database or mail effects may occur during the snippet. The panel should reflect that difference rather than always displaying one queued job.

Changing a selector should start a fresh example run with the chosen configuration applied before setup and service resolution. Recording the resolved choices alongside the output would then make a browser result reproducible in CI. These are implementation suggestions; I haven't exercised them in the PoC.

[shaedrich]

I would also keep the execution mode separate from the connection selector. With a queue fake, the panel counts captured jobs. With the actual sync connection and no fake intercepting dispatch, jobs execute in the current process, so their database or mail effects may occur during the snippet. The panel should reflect that difference rather than always displaying one queued job.

However, allowing not to fake, would require making sure, no mails are sent and the like. This would give one quite an attack surface 🤔

[vynazevedo]

@shaedrich Agreed. My wording was too broad. Executing the job handler should not imply enabling real outbound services.

The queue and mail behavior can be configured independently. For a curated example, the job could execute synchronously against a disposable database while mail is still captured. Laravel's log mail transport is another option for inspecting generated messages without delivering them. The UI could distinguish “handler executed” from “mail captured”.

That configuration alone would not make editable PHP safe, though. Code could bypass the Laravel facades or change configuration. Fakes are useful observation tools, not an isolation boundary. Any execution mode would need the runner to restrict network access outside the snippet's control, including outbound capabilities exposed through a PHP-to-JavaScript bridge, and have no production credentials available.

I would keep the first public version limited to explicitly supported fixtures. If the runner cannot enforce that boundary, leave examples requiring external effects in capture-only or non-runnable mode. I haven't audited the PoC's isolation, so I would not claim its current worker setup provides these guarantees.

[shaedrich]

That configuration alone would not make editable PHP safe, though. Code could bypass the Laravel facades or change configuration. Fakes are useful observation tools, not an isolation boundary. Any execution mode would need the runner to restrict network access outside the snippet's control, including outbound capabilities exposed through a PHP-to-JavaScript bridge, and have no production credentials available.

Correct 👍🏻

I would keep the first public version limited to explicitly supported fixtures. If the runner cannot enforce that boundary, leave examples requiring external effects in capture-only or non-runnable mode.

Sounds reasonable 👍🏻

the job could execute synchronously against a disposable database while mail is still captured.

If would be awesome if when executing a mail example, the snippet widget would then say "You have 1 new email" and you can preview it in this window 🤯