Weave Code
Repdoc Laravel Package
s9e/repdoc
REPdoc is a CLI tool that brings Read-Eval-Print to documentation. It supports Markdown with paired fenced code blocks: a php block to run, immediately followed by an output block (any language) showing the expected printed result.
Read-Eval-Print your doc.
Frequently asked questions about Repdoc
- How do I install REPdoc for Laravel projects?
- Run `composer require s9e/repdoc` in your Laravel project. No additional Laravel-specific setup is needed, as REPdoc is a standalone CLI tool. Use it directly via `vendor/bin/repdoc` or wrap it in an Artisan command for Laravel integration.
- Can REPdoc validate Laravel-specific code examples (e.g., Eloquent queries)?
- Yes, REPdoc executes PHP code, so Laravel classes and methods work as long as dependencies are available. For testing, mock external services or use Laravel’s service container. Sandboxing (e.g., Docker) is recommended for production use.
- What Laravel versions does REPdoc support?
- REPdoc itself has no Laravel version dependency, but it requires PHP 8.1+. Ensure your Laravel app’s PHP version matches REPdoc’s requirements. Test with your Laravel version (e.g., 10.x) to confirm compatibility with custom wrappers.
- How do I integrate REPdoc into Laravel’s CI/CD pipeline?
- Add a GitHub Action or GitLab CI step to run `vendor/bin/repdoc` on your Markdown files. Fail the build if examples don’t match expected outputs. Example: Use `on: [push, pull_request]` to validate docs before merging.
- Is REPdoc safe for production? What about security risks?
- REPdoc uses `eval()`, which is risky. Mitigate this by sandboxing evaluations (e.g., Docker containers or libraries like `box/spout`). Log all executed files and outputs for auditing. Avoid running untrusted docs in production.
- How do I handle missing Laravel dependencies in REPdoc examples?
- Mock dependencies in your Markdown files or use Laravel’s service container. For example, inject a fake `User` model in your test environment. Avoid hardcoding global dependencies like `config('app.env')` in docs.
- What’s the best way to structure REPdoc Markdown files?
- Pair each PHP code block with a language-agnostic output block (e.g., `plain` or `text`). Keep examples minimal and self-contained. Use VS Code snippets to reduce syntax errors. Example: Place docs in `docs/api/` and validate them via CI.
- Can I cache REPdoc outputs to speed up CI/CD?
- Yes, cache evaluated outputs (e.g., in Redis) to avoid reprocessing unchanged files. Use Git diffs to re-run only modified docs. For large projects, parallelize evaluations with Laravel’s `parallel:for` or Symfony’s `Process`.
- Are there alternatives to REPdoc for Laravel?
- Alternatives include custom scripts with `eval()` + sandboxing, or tools like `phpdocumentor` (for static analysis). REPdoc’s unique advantage is live execution with Markdown integration. For stricter security, consider Docker-based solutions like `docker-php-source`.
- How do I troubleshoot REPdoc errors in Laravel?
- For PHP errors, wrap REPdoc in a `try-catch` to log details. If Laravel classes are missing, mock them in the test environment. Permission issues? Ensure docs are readable by the PHP process (`chmod 644`). Slow performance? Cache outputs or limit REPdoc to critical docs.
Weaver
How can I help you explore Laravel packages today?