PHP Documentor 2 v3.0.0 Release Notes
Release Date: 2020-10-27 // over 3 years ago-
phpDocumentor v3.0.0 is here
🚀 After years of development, we are finally able to announce the official release of phpDocumentor version 3. This release has large changes under the hood. We improved the way phpDocumentor detects types in your DocBlocks, allow all kinds of modern type notations, and we speed up the reflection of your code even more. A full parse of a framework with the size of Symfony is completed within a few seconds now.
A brief overview of the largest changes since v2 below.
0️⃣ A brand new default template!
💅 We revised the way we are supporting templates and template customization. phpDocumentor was shipped with a large set of templates. Which was a burden to maintain. It was hard to customize the existing templates which forced our users to copy templates for even the smallest style changes. We have been redesigning our template system, which resulted in a brand new template called: Default.
0️⃣ If you want to change the colours to match your project's own colour scheme, you just need to set a number of CSS variables. If you want to do more complex changes, you can simply overwrite parts of the template. Our new "Default" template is built with components in mind, using small twig template files. These allow you to change just that what you need to change, without having to create a whole template yourself.
👀 Previously, XML templates seemed to be a nice way to write templates but the user experience was not what we expected from it. XSLT was too complex to write and with the improved template, we didn't feel the need for an XML based template anymore. We moved the existing XML template to a new twig based rendered XML output to keep a backward compatibility layer for tools consuming the XML structure.
Full-text Search
📚 The new Default template comes with a brand new full-text search engine. For your convenience, we added support for full-text search that works even when you are offline. This allows you to search for the elements you are looking for, without browsing the documentation for hours.
👌 Support for native type-hints
With the introduction of scalar type-hints, DocBlocks are not required for all function arguments anymore. PhpDocumentor will now read all native type-hints from your code. This allows you to focus on what is important, your code, and write proper descriptions. There will always be situations where you want to give more detailed type-hints for your function arguments, phpDocumentor will prioritize DocBlock type-hints over native types so you have total control.
👌 Support for Generics
📚 With more and more static analysis features being introduced in PHP; DocBlocks are changing. phpDocumentor is now able to understand generics and generic-like array notations; this allows you to use phpDocumentor with every modern codebase and gives you the advantage of clickable types in your documentation.
🆕 New configuration structure
🔧 To prepare for the future, phpDocumentor comes with a new configuration structure. We kept backward compatible support for the v2 format, so from a user point of view, there is nothing to worry about until you want to start using some of our future features. The XSD provided in this repository will help you to write the new configuration.
👌 Improved description rendering
💅 The new template is using a new
descriptionfilter to process all inline tags in a description. This allows us to better style the templates. Inline links are now rendered as real links and references to other elements are also displayed as actual links.
The inline@internaltags are now completely hidden when needed, and descriptions are now fully compatible with PSR-5.💥 Breaking changes
phpDocumentor is a complex application and we do have a number of backward compatibility breaks. Below, we list the most important ones.
⬇️ Dropped plugin support
phpDocumentor v2 was build using the micro-framework Cilex. With the introduction of Symfony Flex, the support of Cilex was stopped. So we switched to a full-blown Symfony-based application. This means that a lot of phpDocumentor's internals have been changed. Which also led to the drop of plugin support, for now. We are planning to re-introduce extensions in a better way in a future version.
⬇️ Dropped official Composer support
🐳 phpDocumentor's libraries used to reflect your codebase are used in many projects. (i.e. Symfony, PHPUnit, Laravel, and phpstan; to name a few) Besides that, phpDocumentor is a complex application with a lot of dependencies. So it is very likely your project dependencies will conflict in some way with our dependencies. We will keep phpDocumentor available on Packagist but we will not provide any support using this installation method. phpDocumentor is shipped as a PHAR and Docker image, which contains everything you need to run phpDocumentor.
What's next?
📚 It has taken us a few years to get to this point, but this is not the end by far. Our vision with phpDocumentor is to make it the one-stop go-to tool when it comes to all your documentation needs. You can expect to hear more about the following features:
- 📚 Including hand-written documentation using Restructured Text (our own documentation is already using an alpha version of this feature!)
- 👌 Support for multiple versions of your project
- Rendering in-line UML diagrams using PlantUML
- 📚 Rendering multiple codebases into one set of documentation, for example: when you have Components
- 📚 Directly generating documentation sources from a git repository
- And much more!
📚 We want to make sure that writing your documentation is as easy as can be.
Previous changes from v3.0.0-rc
-
🛠 This first release candidate contains a number of bugfixes reported since the release of the first beta release. Thanks for all the reports we got! No new features are introduced in this release.
Call for feedback
🚀 PhpDocumentor is developed by a small team with limited time. Our current code base is not fully covered by automated tests. So we are not able to find all regressions or missing features. We would be very grateful when you provide us feedback on this beta release to improve the quality of phpDocumentor.
🔄 Changelog
The full changelog can be found in our changelog file