- How do I integrate this package into my Laravel project’s PHPStan setup?
- Add it to your `composer.json` under `require-dev`, then configure `phpstan.neon` to include your markdown files (e.g., `docs/**/*.md`). The package extends PHPStan’s rules, so no additional tooling is needed beyond your existing setup.
- Does this work with Laravel’s markdown-based documentation (e.g., API docs or READMEs)?
- Yes, it’s designed for Laravel projects. Scan paths like `docs/` or `README.md` in your `phpstan.neon` config, and it will validate all PHP code snippets in those files using PHPStan’s static analysis.
- Will this break CI if my docs contain dynamic snippets (e.g., CLI commands or runtime-generated code)?
- It may trigger false positives for dynamic snippets. Mitigate this by excluding problematic paths or adding `@var` annotations. Start with warning-only mode in CI to test before blocking PRs.
- What Laravel versions or PHPStan versions does this package support?
- The package works with any Laravel version but requires PHPStan ≥1.10.0. Since it’s a PHPStan extension, it’s compatible with modern Laravel apps already using static analysis.
- Can I customize error messages for failed doc snippets (e.g., point to line numbers)?
- Yes, the package provides detailed error output including file paths and line numbers. You can further customize messages via PHPStan’s configuration or post-process logs in CI.
- How do I handle code blocks without `<?php` tags in my markdown files?
- By default, the package auto-prepends `<?php` to snippets missing the tag. Disable this with `prependOpenTagWhenMissing: false` in your `phpstan.neon` if you prefer strict validation.
- Is this package suitable for large Laravel projects with hundreds of markdown files?
- Performance can be managed by excluding non-critical paths (e.g., `docs/legacy/`) or using PHPStan’s `--parallel` flag. Cache results in CI to avoid rescanning unchanged files.
- What alternatives exist for validating doc code snippets in Laravel?
- Manual review or custom scripts are common alternatives, but this package automates validation via PHPStan. For broader language support, consider tools like `doctest` (Python) or `jsdoc-to-markdown`, but none match PHPStan’s depth for PHP.
- How do I exclude certain markdown files or paths from analysis?
- Use glob patterns in your `phpstan.neon` config to target specific files (e.g., `docs/**/*.md`). Exclude paths by omitting them or adding `!path/to/exclude` to the glob list.
- Does this package support strict_types for auto-prepended PHP tags?
- Yes, it enables `strict_types=1` when auto-prepending `<?php` unless disabled via `setStrictTypesWhenOpenTagMissing: false`. This ensures consistent type safety across all validated snippets.