Rule Doc Generator Contracts Laravel Package

Getting Started

Start by installing the package as a dev dependency: composer require --dev symplify/rule-doc-generator-contracts. Then, locate and implement the RuleDocumentationInterface in your custom rule classes — this is your primary entry point. As a Laravel developer, you’ll use this when building reusable StaticAnalysis or Rector-like tools for your codebase (e.g., internal coding standards enforcement), where consistent rule documentation is needed across projects. Your first step is to define basic metadata: rule title, description, and code examples.

Implementation Patterns

Integrate by decorating your rule classes with RuleDocumentationInterface, then programmatically consume the metadata in CLI tools, Laravel commands, or documentation generators. For example:

• Create a php artisan docs:rules command that scans your app’s rules directory and renders HTML/Markdown docs.
• Embed getDescription() output as inline IDE hints or hover tooltips in custom language servers.
• Reuse getInvalidCode()/getValidCode() to auto-generate before/after diffs in your CI reports or Confluence pages. This pattern keeps your rule metadata executable — not just comments — enabling automated validation, searching, and filtering of rules in tooling ecosystems.

Gotchas and Tips

• The package has no runtime behavior — it’s only interfaces. If your rule doesn’t implement the contract, doc generation silently skips it. Always verify instanceof RuleDocumentationInterface before consuming data.
• Metadata drift is common: Titles/descriptions often become stale. Add a phpunit test that asserts getDescription() isn’t empty or contains a versioned changelog hint.
• No built-in autodiscovery or configuration — you’ll need to maintain a registry of rules manually or via reflection. For large codebases, build a static cache of metadata to avoid repeated class instantiation.
• Minimize coupling: Avoid referencing full generators (e.g., symplify/rule-doc-generator) in production. Keep this dependency strictly in require-dev and isolated to doc-generation scripts.
• Tip: Use the same markdown in getDescription() for both CLI usage (php artisan rules) and user-facing docs — consistency reduces maintenance cost and improves adoption.