# phpstan/phpdoc-parser architecture

> Architecture diagram of the GitHub repository phpstan/phpdoc-parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phpstan/phpdoc-parser
- Repository: https://github.com/phpstan/phpdoc-parser

## Overview

This project is a PHP library whose main purpose is to parse PHPDoc blocks into an Abstract Syntax Tree (AST) and enable modifications (including format-preserving printing) of PHPDoc comments. It serves as a core component used primarily by PHPStan for advanced PHPDoc handling, though it also supports Doctrine Annotations.

##### Main Components
- Lexer Component: Located in src/Lexer, this component tokenizes PHPDoc comments into tokens.
- Parser Components:
– PhpDocParser (in src/Parser) that orchestrates parsing.
– ConstExprParser and TypeParser, which handle constant expressions and types respectively.
– TokenIterator that processes the tokens produced by the Lexer.
- AST Representation:
– A robust hierarchy of AST nodes in the src/Ast directory (including specialized nodes for PHPDoc handling, types like IdentifierTypeNode, union/intersection types, annotations, and PHPDoc tags).
- Node Traversal/Visitors:
– The NodeTraverser and NodeVisitor (e.g., CloningVisitor within src/Ast/NodeVisitor) enable manipulations over the AST.
- Printer Component:
– Found in src/Printer, responsible for printing the AST back to a PHPDoc string while preserving the original formatting when possible.
- Configuration:
– ParserConfig (in src/ParserConfig.php) which is used to enable specific lexer attributes (such as lines, indexes, comments).
- Auxiliary/Support Components:
– The “apigen” directory for generating API documentation/themes.
– Documentation files (in the doc directory) describing the grammar rules and supported constructs.
- Testing Framework:
– A comprehensive test suite under tests which validates the parsing, AST generation, traversal, and printer functionalities.

##### Relationships and Data Flow
- Input Flow: A PHPDoc string is first passed to the Lexer, which tokenizes the input.
- Parsing Flow: Tokens are fed into the TokenIterator. The Parser (PhpDocParser) works with the TypeParser and ConstExprParser to generate an AST representing the PHPDoc structure.
- Transformation Flow: The AST can be traversed and manipulated using NodeTraverser with various NodeVisitor implementations—for example, cloning the AST before modifications.
- Output Flow: The Printer component uses the modified AST along with the original tokens (for format preservation) to generate an updated PHPDoc comment.
- Configuration Flow: The ParserConfig influences the behavior of both the Lexer and the Parser, determining which attributes to use during tokenization and parsing.

##### Architectural Patterns and Principles
- Layered Architecture:
– Tokenization, parsing, AST representation, AST manipulation, and printing are structured in separate but interacting layers.
- Separation of Concerns:
– Each module is dedicated to a specific task (e.g., lexing, parsing, printing), making the system modular and easier to test.
- Extensibility:
– The design allows for easy extension by adding new AST node types or parser constructs (for instance, to support new PHPDoc features or additional annotation styles).
- Similarities to Compiler Architecture:
– Input (document) → Lexical Analysis → Parsing → AST → Transformations → Code Generation (or, in this case, re-printing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        input("PHPDoc Input"):::inputStyle
        config("ParserConfig"):::configStyle
    end

    %% Lexical Analysis Layer
    subgraph "Lexical Analysis Layer"
        lexer("Lexer"):::processing
        tokenIterator("TokenIterator"):::processing
    end

    %% Parsing Layer
    subgraph "Parsing Layer"
        phpdocParser("PhpDocParser"):::processing
        constExpr("ConstExprParser"):::processing
        typeParser("TypeParser"):::processing
    end

    %% AST and Transformation Layer
    subgraph "AST & Transformation Layer"
        ast("AST Representation"):::processing
        traverser("Node Traverser"):::processing
        cloningVisitor("CloningVisitor"):::processing
    end

    %% Output Layer
    subgraph "Output Layer"
        printer("Printer"):::processing
        output("Formatted PHPDoc Output"):::outputStyle
    end

    %% Auxiliary & Testing Components
    subgraph "Auxiliary & Testing"
        auxDoc("Documentation (doc)"):::aux
        auxApigen("API Generation (apigen)"):::aux
        tests("Testing Suite (tests)"):::aux
    end

    %% Data Flow
    input --> lexer
    lexer --> tokenIterator
    tokenIterator --> phpdocParser
    phpdocParser --> ast
    ast --> traverser
    traverser --> cloningVisitor
    cloningVisitor --> printer
    printer --> output

    %% Parser internal dependencies
    phpdocParser --> constExpr
    phpdocParser --> typeParser

    %% Configuration influences (bidirectional connection for conceptual clarity)
    config --- lexer
    config --- phpdocParser

    %% Auxiliary connections (side notes)
    auxDoc --- config
    auxApigen --- auxDoc
    tests --- ast

    %% Click Events
    click lexer "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Lexer/Lexer.php"
    click tokenIterator "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Parser/TokenIterator.php"
    click phpdocParser "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Parser/PhpDocParser.php"
    click constExpr "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Parser/ConstExprParser.php"
    click typeParser "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Parser/TypeParser.php"
    click ast "https://github.com/phpstan/phpdoc-parser/tree/2.1.x/src/Ast"
    click traverser "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Ast/NodeTraverser.php"
    click cloningVisitor "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Ast/NodeVisitor/CloningVisitor.php"
    click printer "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/Printer/Printer.php"
    click config "https://github.com/phpstan/phpdoc-parser/blob/2.1.x/src/ParserConfig.php"
    click auxDoc "https://github.com/phpstan/phpdoc-parser/tree/2.1.x/doc"
    click auxApigen "https://github.com/phpstan/phpdoc-parser/tree/2.1.x/apigen"
    click tests "https://github.com/phpstan/phpdoc-parser/tree/2.1.x/tests"

    %% Styles
    classDef processing fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef configStyle fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef inputStyle fill:#A3E4D7,stroke:#117864,stroke-width:2px;
    classDef outputStyle fill:#D5F5E3,stroke:#145A32,stroke-width:2px;
    classDef aux fill:#FAD7A0,stroke:#784212,stroke-width:2px;
```
