Releases: phpDocumentor/phpDocumentor
v3.7.1
v3.7.0
3.7.0
This release is mostly a maintenance release. With some small improvements on the output of phpDoc on the cli. And internal upgrades of a number of dependencies. Most note worthy changes are listed in these release notes.
Clean template refactoring
Thanks to @omegamvc the clean template has been updated to work better on mobile devices and new features added to the default template for api docs have been added. This is a huge step forward in the clean template. The work has not been finished yet. So more will follow in the future.
- Complete refactoring clean template - First Steep by @omegamvc in #3846
- Fix CSS to improve display on mobile devices by @omegamvc in #3847
PHP 8.3 and PHP 8.4 support
phpDocumentor is now executable on php 8.3 and 8.4 This does not mean we have support for all language additions yet. As we told in the previous release notes the impact of php 8.4 is very big. A lot of changes have to be done to be able to support php 8.4 language features.
Improved config options for plantuml
Since a few releases phpDocumentor is using plantuml to generate diagrams. However some users did experience issues when using the phar install of phpDocumentor. While to docker based installations did work as expected. To make it possible again to generate diagrams using the phar based installations we did add some new options. These new options will allow you to install plantuml on your system and point phpdocumentor to the correct location. The options are added to the docs: https://docs.phpdoc.org/guide/guides/generate-diagrams.html#generate-diagrams
[BETA] Custom twig extensions
We did introduce an extension system to phpDocumentor a few releases ago. However there was no real working use-case for extensions yet. In this release we did add an example on how to extend phpDocumentor with a custom twig extension. More extension points will be added in the future. If you want to create your own twig extension read the guide on how to do that: https://docs.phpdoc.org/guide/features/extensions/twig-extension.html#twig-extension
Other changes
- Improve output formating by @jaapio in #3870
- Bump guides to v1.7 by @jaapio in #3871
- Docs: fix link in generating-documentation.rst by @ThatsJustCheesy in #3851
New Contributors
- @omegamvc made their first contribution in #3846
- @ThatsJustCheesy made their first contribution in #3851
Full Changelog: v3.6.0...v3.7.0
Contributors
Assets 4
v3.6.0
What's Changed
In this release a number of bugfixes have been added and two major new features. We are still working on php 8.3 and 8.4 support to ensure our users are able to upgrade. But due to the large changes that are required with the new property hooks in php 8.4 and async property accessors a lot of work has to be done. Neverless we are very happy to provide you this new release which will definitely help you to document your projects even better.
Markdown support
Most important change in this release is the introduction of markdown support in guides. Before phpDocumentor did only have support for ReStructedText in the manuals. By now we also support markdown. The syntax of markdown is not as extendable as the RST syntax is. Therefor the more advanced features like class listing and automated diagrams are not supported yet. But for most common usecases markdown will work.
Improved class diagrams
In this release we added an improved version of the class diagram generation. We extended the way we generate diagrams, so external classes are now better visible. And also the style of traits in the class diagram has been improved. We are planning to add more options and allow users to get more control over the generated diagram, by filtering out certain elements.
Other changes:
- GH Actions: fix up action runner version by @jrfnl in #3764
- feat: open rendered SVGs in separate tab/window onclick by @dgoosens in #3793
- trait.html.twig: Fix deprecated constant(s) by @adriendupuis in #3840
- Implement new improved class diagram generator by @jaapio in #3839
- Filter empty namespaces from all indexes by @jaapio in #3841
- Add option disable packages from menu by @jaapio in #3842
New Contributors
- @matsuo made their first contribution in #3766
- @dgoosens made their first contribution in #3793
- @agung2001 made their first contribution in #3796
Full Changelog: v3.5.3...v3.6.0
Contributors
Assets 4
v3.5.3
v3.5.3
- [BUG] Resolve issue with invalid image paths in guides
- [BUG] Fix inclosed tag in sidebar template
- [BUG] Resolve visual issue in guides with large code blocks.
- [FEATURE] filter empty namespace by @jaapio in #3740
Full Changelog: v3.5.2...v3.5.3
Contributors
Assets 4
v3.5.2
v3.5.1
#v3.5.1
This bugfix release includes 2 small bugfixes regarding the cli options you can pass to phpdoc. before we supported phpdoc run -d ./src and phpdoc -d ./src both would do exactly the same. During a change in the previous version the first way of doing things was broken. Now this has been restored. Including the option to list possible settings with --list-settings
Also included is a new way of rendering the new php 8.4 #[Deprecated] attribute as well the improved rendering of deprecated methods and classes.
Full change list:
- Fix typo in configuration.rst by @adriendupuis in #3724
- Add support for #[Deprecated] by @jaapio in #3731
- Fix settings:list and --list-settings not working by @Mai-Lapyst in #3732
- Reintroduce multicommand interface by @jaapio in #3736
New Contributors
- @adriendupuis made their first contribution in #3724
- @Mai-Lapyst made their first contribution in #3732
Full Changelog: v3.5.0...v3.5.1
Contributors
Assets 4
v3.5.0
Guides, php 8.3 and more!
In this new release of phpDocumentor you will find a large number of improvements and new added support for php language constructs. But also a large number of improvements to write better and more useful documentation for your fellow developers.
Guides 1.3
We have been working very hard together with the Typo3 Documentation team, but also with members of the Doctrine and Symfony project to stabilize the ReStructuredText support in phpDocumentor. The release the first stable version was a few months ago and was already included in the docker image we publish on docker hub. But wasn't part of a tagged release yet, until now. The new version is better in almost every perspective. We will keep tuning and improving the guides project.
Class list directive
A new directive added in this version the dynamic class list. In many situations I found my self creating list of classes implementing a certain interface to describe they are available for certain purpose. But I also wrote documentation above each class. So why not combining those?
.. phpdoc:class-list:: [?(@.inheritedElement == "\phpDocumentor\Transformer\Writer\WriterAbstract")]
.. phpdoc:name::
.. phpdoc:summary::
https://docs.phpdoc.org/guide/internals/templates/index.html#templates
Class diagrams
Another directive we added is the class diagram directive. phpDocumentor could already create a class diagram out of your full code base. But for larger projects this was barely useful. The new class diagram directive allows you to select a number of classes and create a diagram out of those. For example to just select the domain of your application or any other specify system that you want to visualize.
.. phpdoc:class-diagram:: [?(@.namespace starts_with "\phpDocumentor\Descriptor")]
https://docs.phpdoc.org/guide/hand-written-docs/directives.html#directives
Attributes
PHP introduced attributes in php 8. We did never add them to the API documentation because it didn't seem to add value. Now attributes are more widely adopted in the eco system we are also introducing them into phpDocumentor. Right now we will only display them as elements on the API docs, but more improvements will follow.
Other changes
Template extension
since the release of the v3 series we have been working on our new default template and make it as easy as possible to extend that template, by changing the color scheme adding custom css and even replacing full components in the template. But in some cases this isn't enough. You want to add custom reports or other pages, in this version we added template extending. When you extend an existing template you can still use the power off all the features we had before, but also include more customizations overviews and more.
In development
Extensions
We are working on a new way to extend phpDocumentor. In our vision phpDocumentor will become a documentation framework. Because we know more about the code base than what you write down in the docblocks. Example usecase for extensions are custom writers, that allow you to not just write to file but push your documentation to a api? Extract all hooks from your wordpress plugins and more? This feature is currently in development, and will be extended more. With the goal to make phpDocumentor an even more useful tool in our toolbox.
Markdown support
Markdown is a very common format to write documents. We do see more value in RST but as many people are using markdown to write docs we are also adding CommonMark support to phpDocumentor. The feature set of markdown will be limited, but you might find it working for you.
Other note worthy changes
- Do not install with untrusted signature through PHIVE by @ravage84 in #3597
- Fix: resolves issue with varidict arguments by @jaapio in #3600
- Feat: Add filter for var tags on groups by @jaapio in #3602
- Fix: add resolver for methods and properties by @jaapio in #3614
- Upgrade guides to latest version by @jaapio in #3619
- Upgrade guides to 2023-12-13 version by @jaapio in #3627
- Add directive to list classes by their parent by @jaapio in #3631
- Fix single command run by @jaapio in #3634
- Fix wrong value for visibility option in XSD by @sebastian-meyer in #3663
- Fix wrong value for visibility option in XSD by @sebastian-meyer in #3666
- Fix Psalm issue by @sebastian-meyer in #3672
- Small improvements to guide rendering by @sebastian-meyer in #3671
- Add test for Guides Compiler by @mvriel in #3676
- Add test for DescriptorRepository by @mvriel in #3675
- Add CSS background colour for body by @DanielSiepmann in #3680
- Changing GitHub Action entrypoint format by @vcampitelli in #3685
- Checking if the template location was provided before parsing it by @vcampitelli in #3686
- [DOCS] Fix generating-documentation.rst by @justbyitself in #3687
- fix: typo in CI docs by @stobrien89 in #3690
- fix: typo in the typo fix by @stobrien89 in #3691
- Update Twitter icon to X by @fulldecent in #3693
- Remove note about future v3 release by @fulldecent in #3696
- Phpunit upgrade by @jaapio in #3712
- Fix issue with inheritance order by @jaapio in #3713
- Inherit method documentation through multiple generations by @smaddock in #3701
- Add gpg key to install instruction, fixes #3694 by @fulldecent in #3699
- Add tests for Version Compiler Passes and refactor TableOfContentsBuilder by @mvriel in #3677
- Bump to fixed reflection docblock by @jaapio in #3718
New Contributors
- @ravage84 made their first contribution in #3597
- @sebastian-meyer made their first contribution in #3663
- @DanielSiepmann made their first contribution in #3680
- @vcampitelli made their first contribution in #3685
- @justbyitself made their first contribution in #3687
- @stobrien89 made their first contribution in #3690
- @fulldecent made their first contribution in #3693
- @smaddock made their first contribution in #3701
Full Changelog: v3.4.3...v3.5.0
Contributors
Assets 4
v3.5.0-rc
Guides, php 8.3 and more!
In this new release of phpDocumentor you will find a large number of improvements and new added support for php language constructs. But also a large number of improvements to write better and more useful documentation for your fellow developers.
Guides 1.3
We have been working very hard together with the Typo3 Documentation team, but also with members of the Doctrine and Symfony project to stabilize the ReStructuredText support in phpDocumentor. The release the first stable version was a few months ago and was already included in the docker image we publish on docker hub. But wasn't part of a tagged release yet, until now. The new version is better in almost every perspective. We will keep tuning and improving the guides project.
Class list directive
A new directive added in this version the dynamic class list. In many situations I found my self creating list of classes implementing a certain interface to describe they are available for certain purpose. But I also wrote documentation above each class. So why not combining those?
.. phpdoc:class-list:: [?(@.inheritedElement == "\phpDocumentor\Transformer\Writer\WriterAbstract")]
.. phpdoc:name::
.. phpdoc:summary::
https://docs.phpdoc.org/guide/internals/templates/index.html#templates
Class diagrams
Another directive we added is the class diagram directive. phpDocumentor could already create a class diagram out of your full code base. But for larger projects this was barely useful. The new class diagram directive allows you to select a number of classes and create a diagram out of those. For example to just select the domain of your application or any other specify system that you want to visualize.
.. phpdoc:class-diagram:: [?(@.namespace starts_with "\phpDocumentor\Descriptor")]
https://docs.phpdoc.org/guide/hand-written-docs/directives.html#directives
Attributes
PHP introduced attributes in php 8. We did never add them to the API documentation because it didn't seem to add value. Now attributes are more widely adopted in the eco system we are also introducing them into phpDocumentor. Right now we will only display them as elements on the API docs, but more improvements will follow.
Other changes
Template extension
since the release of the v3 series we have been working on our new default template and make it as easy as possible to extend that template, by changing the color scheme adding custom css and even replacing full components in the template. But in some cases this isn't enough. You want to add custom reports or other pages, in this version we added template extending. When you extend an existing template you can still use the power off all the features we had before, but also include more customizations overviews and more.
In development
Extensions
We are working on a new way to extend phpDocumentor. In our vision phpDocumentor will become a documentation framework. Because we know more about the code base than what you write down in the docblocks. Example usecase for extensions are custom writers, that allow you to not just write to file but push your documentation to a api? Extract all hooks from your wordpress plugins and more? This feature is currently in development, and will be extended more. With the goal to make phpDocumentor an even more useful tool in our toolbox.
Markdown support
Markdown is a very common format to write documents. We do see more value in RST but as many people are using markdown to write docs we are also adding CommonMark support to phpDocumentor. The feature set of markdown will be limited, but you might find it working for you.
Other note worthy changes
- Do not install with untrusted signature through PHIVE by @ravage84 in #3597
- Fix: resolves issue with varidict arguments by @jaapio in #3600
- Feat: Add filter for var tags on groups by @jaapio in #3602
- Fix: add resolver for methods and properties by @jaapio in #3614
- Upgrade guides to latest version by @jaapio in #3619
- Upgrade guides to 2023-12-13 version by @jaapio in #3627
- Add directive to list classes by their parent by @jaapio in #3631
- Fix single command run by @jaapio in #3634
- Fix wrong value for visibility option in XSD by @sebastian-meyer in #3663
- Fix wrong value for visibility option in XSD by @sebastian-meyer in #3666
- Fix Psalm issue by @sebastian-meyer in #3672
- Small improvements to guide rendering by @sebastian-meyer in #3671
- Add test for Guides Compiler by @mvriel in #3676
- Add test for DescriptorRepository by @mvriel in #3675
- Add CSS background colour for body by @DanielSiepmann in #3680
- Changing GitHub Action entrypoint format by @vcampitelli in #3685
- Checking if the template location was provided before parsing it by @vcampitelli in #3686
- [DOCS] Fix generating-documentation.rst by @justbyitself in #3687
- fix: typo in CI docs by @stobrien89 in #3690
- fix: typo in the typo fix by @stobrien89 in #3691
- Update Twitter icon to X by @fulldecent in #3693
- Remove note about future v3 release by @fulldecent in #3696
- Phpunit upgrade by @jaapio in #3712
- Fix issue with inheritance order by @jaapio in #3713
- Inherit method documentation through multiple generations by @smaddock in #3701
- Add gpg key to install instruction, fixes #3694 by @fulldecent in #3699
- Add tests for Version Compiler Passes and refactor TableOfContentsBuilder by @mvriel in #3677
- Bump to fixed reflection docblock by @jaapio in #3718
New Contributors
- @ravage84 made their first contribution in #3597
- @sebastian-meyer made their first contribution in #3663
- @DanielSiepmann made their first contribution in #3680
- @vcampitelli made their first contribution in #3685
- @justbyitself made their first contribution in #3687
- @stobrien89 made their first contribution in #3690
- @fulldecent made their first contribution in #3693
- @smaddock made their first contribution in #3701
Full Changelog: v3.4.3...v3.5.0