Skip to content

Feature request: Port PHP parser and API doc generator

Problem Statement

The current Hazaar MVC lacks a built-in PHP code parser that can effectively analyze code for documentation and other purposes. There is existing PHP parser code that I have, but it is outdated and not compatible with modern PHP 8 standards. Additionally, there is no integration with renderers that could use the parsed data to output formats such as Markdown for API documentation.

Who will benefit?

  • PHP developers using Hazaar MVC who need automated documentation generation.
  • Teams looking to maintain consistent and up-to-date documentation for their PHP projects.
  • Developers who want a flexible parser to integrate with various output renderers beyond just Markdown (e.g., HTML, JSON).

Benefits and risks

Benefits

  • Provides automated API documentation generation, improving project maintainability.
  • Modernizes existing parser code to be compatible with PHP 8, enhancing performance and security.
  • Lays the groundwork for additional renderers, making the parser more versatile.

Risks

  • Refactoring old PHP parser code may introduce bugs or require significant testing efforts.
  • Initial implementation might increase complexity in the short term before the benefits are realized.

Proposed solution

Port the existing PHP parser code to Hazaar MVC, updating it to be compatible with PHP 8. Refactor and modernize the parser to handle PHP 8 syntax and features. Design the parser to be modular, allowing integration with different renderers.

For the first implementation, create a Markdown renderer that uses the parsed data to generate API documentation. This Markdown output will include function definitions, class structures, and docblock comments.

Examples

  • PHPDocumentor uses a similar parser-based approach for generating documentation from PHP code.
  • Doctrine Annotations also parse PHP comments to extract metadata.

Priority/Severity

  • High (This will bring a huge increase in performance/productivity/usability/legislative cover)
  • Medium (This will bring a good increase in performance/productivity/usability)
  • Low (anything else e.g., trivial, minor improvements)