PHPDoc parser TypeScript version

Next-gen PHPDoc parser with support for intersection types and generics(TypeScript version)

What's that

This parser is inspired by the PHPStan's phpdoc-parser library: https://github.com/phpstan/phpdoc-parser

This library @rightcapital/phpdoc-parser represents PHPDocs with an AST (Abstract Syntax Tree). It supports parsing and modifying PHPDocs by using TypeScript/JavaScript.

For the complete list of supported PHPDoc features check out PHPStan documentation.

• PHPDoc Basics (list of PHPDoc tags)
• PHPDoc Types (list of PHPDoc types)

Installation

# pnpm
pnpm add @rightcapital/phpdoc-parser
# yarn
yarn add @rightcapital/phpdoc-parser
# npm
npm install --save @rightcapital/phpdoc-parser

Basic usage

import{ConstExprParser,Lexer,PhpDocParser,TokenIterator,TypeParser,}from'@rightcapital/phpdoc-parser';// basic setupconstlexer=newLexer();constconstExprParser=newConstExprParser();consttypeParser=newTypeParser(constExprParser);constphpDocParser=newPhpDocParser(typeParser,constExprParser);// parsing and reading a PHPDoc stringconsttokens=newTokenIterator(lexer.tokenize('/** @param Lorem $a */'));constphpDocNode=phpDocParser.parse(tokens);// PhpDocNodeconstparamTags=phpDocNode.getParamTagValues();// ParamTagValueNode[]console.log(paramTags[0].parameterName);// '$a'console.log(paramTags[0].type);// IdentifierTypeNode { attributes: {}, name: 'Lorem' }

Format-preserving printer

This component can be used to modify the AST and print it again as close as possible to the original.

It's heavily inspired by format-preserving printer component in nikic/PHP-Parser.

import{CloningVisitor,ConstExprParser,IdentifierTypeNode,Lexer,NodeTraverser,PhpDocNode,PhpDocParser,TokenIterator,TypeParser,Printer,}from'@rightcapital/phpdoc-parser';constusedAttributes={lines: true,indexes: true};constlexer=newLexer();constconstExprParser=newConstExprParser(true,true,usedAttributes);consttypeParser=newTypeParser(constExprParser,true,usedAttributes);constphpDocParser=newPhpDocParser(typeParser,constExprParser,true,true,usedAttributes,);consttokens=newTokenIterator(lexer.tokenize('/** @param Lorem $a */'));constphpDocNode=phpDocParser.parse(tokens);// PhpDocNodeconstcloningTraverser=newNodeTraverser([newCloningVisitor()]);const[newPhpDocNode]=cloningTraverser.traverse([phpDocNode])as[PhpDocNode];// change something in newPhpDocNodenewPhpDocNode.getParamTagValues()[0].type=newIdentifierTypeNode('Ipsum');// print changed PHPDocconstprinter=newPrinter();constnewPhpDoc=printer.print(newPhpDocNode);console.log(newPhpDoc);// --- result ---// /**// * @param Ipsum $a// */constnewPhpDocWithFormatPreserving=printer.printFormatPreserving(newPhpDocNode,phpDocNode,tokens,);console.log(newPhpDocWithFormatPreserving);// '/** @param Ipsum $a */'

Welcome to contribute

We are stilling waiting for someones to contribute, especially for the following features.

• Doctrine Annotations support
• More tests
• More docs
• A script to monitor upstream updates and notify the author to catch up.

Please check out our Contribution guide

How did we create the initial version of this project.

We created most of our code by using ChatGPT as a tool to transform most code from https://github.com/phpstan/phpdoc-parser to TypeScript version.

Our PHP API haven't used Doctrine, so Doctrine support are removed.

License

MIT License © 2023-Present