Uptodocs Laravel Package

Getting Started

Start by installing via Composer (composer require mathiasverraes/uptodocs) and creating a Markdown file (e.g., docs/usage.md) with fenced PHP code blocks. Each block is treated as a standalone script—prefix with <?php if needed. Run vendor/bin/uptodocs docs/usage.md to validate and execute snippets. The first use case is testing documentation examples: write a guide with runnable examples, and uptodocs ensures they don’t bitrot by verifying they execute successfully in CI.

Implementation Patterns

• Living Documentation: Embed executable examples in READMEs or docs; CI runs uptodocs to catch breaking changes or outdated APIs.
• Test-Driven Docs: Write usage examples first as Markdown code blocks, then implement the code, running uptodocs as integration tests.
• CI Workflow: Add vendor/bin/uptodocs docs/**/*.md to your CI pipeline to fail builds if any documented snippet throws an error or warning.
• Isolation: Leverage per-block process isolation to test code that modifies global state (e.g., date_default_timezone_set, static properties) without cross-contamination.

Gotchas and Tips

• Timezone & Environment: Each snippet runs in a fresh process—configure date_default_timezone_set() or putenv() inside the snippet if your code depends on environment variables.
• No Autoloading by Default: Include require __DIR__.'/vendor/autoload.php'; at the top of code blocks if your examples rely on Composer autoloaded classes.
• Exit Codes & Output: Uptodocs exits non-zero on any output to STDERR or exceptions; suppress expected warnings with error_reporting(0) or use @ cautiously.
• Staleness Risk: Since the last release was in 2020, verify compatibility with modern PHP versions (8.0+)—test locally before trusting CI.
• Extensibility: Extend the runner via custom output formatters (implement Uptodocs\Output\OutputFormatter) or preprocessor hooks if you need global setup (e.g., mock services).