Rule Doc Generator Laravel Package

Getting Started

Do not use this package in new projects. It is explicitly deprecated and unmaintained. If you’re maintaining a legacy codebase that already uses symplify/rule-doc-generator, begin by:

1. Locating its usage—check composer.json for the dependency and inspect config/doc-generator.php or similar config files.
2. Identifying the CLI entrypoint (e.g., bin/doc-generator or custom Symfony Console command).
3. Running the generator locally to confirm baseline output before making changes.

Your first action should be to plan migration to a supported alternative like Rector (with its rectorphp/rector-docs) or a hand-written, versioned docs system using structured docblocks.

Implementation Patterns

In legacy setups, developers typically:

• Annotated rule classes with custom PHPDoc tags (e.g., @rule-title, @rule-description, @rule-before, @rule-after).
• Registered rule sets in config (e.g., grouped by coding standard or category like EarlyReturn, Strict).
• Used CI to auto-generate docs/rules.md on build, often with --check mode to fail if docs were stale.

⚠️ If forced to extend:

• Override formatters by extending src/Formatter/ classes (hardcoded logic).
• Patch docblock parsing via src/Parser/DocBlockResolver.php (likely uses deprecated phpdocumentor/reflection-docblock).
• Use Twig templates in templates/—but expect compatibility issues with modern PHP/Twig.

Critical: Never add new rules using this generator. Migrate rule documentation to actively supported tools before expanding.

Gotchas and Tips

• Deprecation ≠ Removal: The package may still install, but dependencies (e.g., Symplify components <5.0) conflict with modern Laravel/PHPStan/Rector—expect runtime errors on PHP 8.0+.
• Silent failures: Documentation generation may succeed without updating docs if rule metadata changed subtly (e.g., renamed class property in docblock). Always diff outputs.
• No PSR-12 compliance: Rule docblocks often used non-standard annotations (e.g., @see for rule examples), breaking IDE autocomplete and static analyzers.
• Template fragility: Changes to docblock structure (e.g., adding @phpstan-param) may crash generation. Test upgrades in a branch.
• CI risk: If CI relies on this to verify docs freshness, it may pass while docs are outdated—add manual checks (e.g., grep -r '@rule-before' src/) as backup.
• Escape hatch: Extract docblocks manually, then use PHP-CS-Fixer’s doc generator or Rector’s docs tooling instead.

Bottom line: Treat this as technical debt to be removed, not extended. Prioritize documenting rules inline with modern standards, and retire this package.