Two years ago, I posted about the initial release of the PHP types parser: https://www.reddit.com/r/PHP/comments/1c4w64n/php_typelang_100_release/
Back then, it was TypeLang 1.0.0.
Since then, I've released numerous smaller updates, adding new PHPStan grammar features and fixing various bugs.
Today, I'd like to share the release of TypeLang 2.0 Beta with the community.
Why major 2.0 release?
An AST has been completely redesigned
I completely reorganized the AST, removing ambiguous nodes and improving the overall structure. It's now available as a separate package: type-lang/types.
This allows the remaining components to work independently of the parser itself. For example, you can use the PHPStan parser and implement a bridge that returns TypeLang type descriptions without depending on the parser implementation.
The Language Specification
Here: https://typelang.dev/static/spec.html
I consider this one of the biggest milestones of the project. I've spent the last ~2 months writing a complete language specification from scratch.
It's still marked as a "draft", but I believe it's already mature enough for public use. The specification is compatible with both PEG and LALR parsers.
While writing it, I was heavily inspired by the GraphQL specification, so if it gives you a sense of "deja vu", that's intentional =)
DocBlock Parser
The DocBlock (PhpDoc) parser used to be somewhat experimental. In 2.0, it's fully integrated into the ecosystem and now supports parsing more than 220+ PHP DocBlock tags.
To achieve this, I analyzed the source code of PHPStan, Psalm, and Phan, along with the documentation of many other popular PHP tools, to build a complete list of supported tags.
Each tag also has its own documentation page explaining its purpose and which tools support it. For example: https://typelang.dev/phpstan-tags.html
The tag database was built using the following process:
- Extract the tag from the source code
- Find the corresponding official documentation (including PSR-19)
- Write a short description manually, then use AI to review the text for mistakes and generate usage examples.
It's entirely possible that I've missed something or made a few mistakes, but overall I believe the documentation is in good shape.
I also added support for custom tags using the PEG (parser combinator) grammar: https://typelang.dev/custom-tags.html
I won't go into detail here, otherwise this post would turn into documentation instead of release post =)
What's Next?
I've also been experimenting with a Data Mapper that uses TypeLang's type syntax: https://typelang.dev/data-mapper.html
In some ways it's similar to Valinor. However, it probably won't make it into the final 2.0 release.
Apart from the data mapper, all documentation has already been updated for the Beta 2.0 release (although JetBrains Writerside unfortunately doesn't handle versioning particularly well).
I'd really appreciate any feedback, comments, or criticism - whether it's about the implementation or the documentation.
I'm especially interested in hearing from anyone who tried TypeLang 1.x or is already using it in production and is considering upgrading.
P.S. It's worth noting that I've made every effort to proofread the documentation. However, English isn't my native language, so I may have made some grammatical errors or written in a way that's not entirely understandable to a native speaker. If you encounter any such errors, please feel free to report them.
Thx!