Releases: phpDocumentor/phpDocumentor
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
Contributors
Assets 4
v3.4.3
v3.4.2
v3.4.1
v3.4.0
What's new in phpDocumentor 3.4.0
Our ReStructuredText library as taken flight. It's now a separate library and can be used in any project. As
it is getting more and more traction the library is becoming more feature complete and stricter accoring to the RST spec.
This allows you to write better documentation for your users but also improved the readability of our own docs.
Changelogs of the guides library are not included in these release notes.
General changes
In this release we dropped PHP 7 support completely, we upgraded to Symfony 6 and added support for php 8.2
Interally we have restructured the pipelines to prepare for multi version support in the future.
Added
- Add used-by resolving by @jaapio in #3198
- Query engine for AST by @jaapio in #3172
- Rfc/3154 full line and column location of methods by @LeoVie in #3214
- Support null versions in Since reflection by @mvriel in #3286
- Source code cannot be viewed from packages, file or namespaces by @mvriel in #3284
- When typing an array, show that in docs by @mvriel in #3293
- GH#3307 Make readonly mutator for class available by @mvriel in #3362
Template
- Tighten table of contents by @mvriel in #3382
- Introduce the first value objects by @mvriel in #3381
- Show 'On this page' for classes and namespaces by @mvriel in #3383
- Restyle elements and add color support by @mvriel in #3388
- Do not show container section of TOC in classes by @mvriel in #3380
- Back to top doesn't work in Guides by @mvriel in #3391
- Show whether a method is tagged as 'api' by @mvriel in #3392
- Show Constants on Traits in the Trait's documentation by @mvriel in #3394
- Move headerlinks to component by @mvriel in #3404
- feat: preserve newlines in XML attributes by @bshaffer in #3430
- Including Punctuation Marks by @BirdboyBolu in #3439
- feat: add support for
APP_CACHE_DIRandAPP_LOG_DIRby @drupol in #3518 - feat: add class magic methods to xml template, fix magic method return tag by @bshaffer in #3514
- Add callable rendering by @jaapio in #3538
- Feature/filesource tag by @jaapio in #3539
- feat: add magic flag to xml template by @bshaffer in #3520
Fixed
- fix: ensure uses/see/link descriptors render to string as expected by @bshaffer in #3244
- Fix OutputHello Example Param Wording by @CraicOverflow89 in #3324
- Fix issue with minimal directory by @jaapio in #3325
- Fix: remove redundant whitespace by @kudashevs in #3335
- Docker shouldn't run
help runby default by @mvriel in #3285 - Levenshtein argument too long by @mvriel in #3287
- References to cases are not linked by @mvriel in #3288
- Purge caches upon version change by @mvriel in #3289
- Extend timeout for UML generation to 20mins by @Hackwar in #3311
- Should fix #3415 by @peterhauke in #3441
- Resolve issue invalid property definition by @jaapio in #3479
- Bugfix/3494 ignore symlinks by @jaapio in #3495
Docs
- Start documenting pipelines and remove obsolete pipeline by @mvriel in #3483
- [DOCS] Link to configuration chapter by @linawolf in #3489
- [DOCS] Fix indentation to make code-blocks render by @linawolf in #3490
CI
- More strict argument check by @jaapio in #3195
- Reintroduce composer require checker by @jaapio in #3133
- Line numbers show 0 with InvalidTag issues by @mvriel in #3294
- Windows tests keep failing by @mvriel in #3295
- GH Actions: bust the cache semi-regularly by @jrfnl in #3357
- Start building on php 8.2 by @jaapio in #3376
- Use centralized phar build by @jaapio in #3529
- Comment use of unreleased method from ReflectionDocBlock by @mvriel in #3364
- Moved most parts of the DescriptorAbstract and TagDescriptor into traits by @mvriel in #3375
- Introduce CanHaveAType and CanHaveADefaultValue traits for Descriptors by @mvriel in #3379
Other
- Refactor LinkRenderer into a series of adapters and introduce references to guides by @mvriel in #3475
- Warn when multiple versions and/or sets of each type is given by @mvriel in #3477
- Move Files listing from Project to Documentation Sets by @mvriel in #3480
- Move indexes from Project to Documentation Sets by @mvriel in #3481
- Remove file and index getters and setters from project by @mvriel in #3482
- Extract pipeline for documentation set by @mvriel in #3485
- Collect files and indexes in API Documentation Set by @mvriel in #3486
- Cache per documentation set by @mvriel in #3487
- Move compiling into a pipeline by @mvriel in #3488
- Refactor all compilers to work on a DocumentationSet by @mvriel in #3492
- Change writers to be performed on a per-documentation-set basis by @mvriel in #3496
- Drop php 7.4 and php 8.0 by @jaapio in #3510
- Restructure compiler to allow different stages by @jaapio in #3519
- Php upgrade by @jaapio in #3540
- Chore: upgrade to symfony 6 by @jaapio in #3541
New Contributors
- @LeoVie made their first contribution in #3214
- @wouterj made their first contribution in #3218
- @bshaffer made their first contribution in #3244
- @amayer5125 made their first contribution in #3312
- @Hackwar made their first contribution in #3311
- @CraicOverflow89 made their first contribution in #3324
- @kudashevs made their first contribution in #3335
- @BirdboyBolu made their first contribution in #3439
- @peterhauke made their first contribution in #3441
- @linawolf made their first contribution in #3489
- @drupol made their first contribution in #3518
Full Changelog: v3.3.1...v3.4.0-rc
Contributors
Assets 4
v3.4.0-rc.2
Fixes
- Signed phar release
v3.4.0-rc
What's new in phpDocumentor 3.4.0
Our ReStructuredText library as taken flight. It's now a separate library and can be used in any project. As
it is getting more and more traction the library is becoming more feature complete and stricter accoring to the RST spec.
This allows you to write better documentation for your users but also improved the readability of our own docs.
Changelogs of the guides library are not included in these release notes.
General changes
In this release we upgraded to Symfony 6 and PHP 7 support has been droppped completely. We added support for php 8.2.
Interally we have restructured the pipelines to prepare for multi version support in the future.
Added
- Add used-by resolving by @jaapio in #3198
- Query engine for AST by @jaapio in #3172
- Rfc/3154 full line and column location of methods by @LeoVie in #3214
- Support null versions in Since reflection by @mvriel in #3286
- Source code cannot be viewed from packages, file or namespaces by @mvriel in #3284
- When typing an array, show that in docs by @mvriel in #3293
- GH#3307 Make readonly mutator for class available by @mvriel in #3362
Template
- Tighten table of contents by @mvriel in #3382
- Introduce the first value objects by @mvriel in #3381
- Show 'On this page' for classes and namespaces by @mvriel in #3383
- Restyle elements and add color support by @mvriel in #3388
- Do not show container section of TOC in classes by @mvriel in #3380
- Back to top doesn't work in Guides by @mvriel in #3391
- Show whether a method is tagged as 'api' by @mvriel in #3392
- Show Constants on Traits in the Trait's documentation by @mvriel in #3394
- Move headerlinks to component by @mvriel in #3404
- feat: preserve newlines in XML attributes by @bshaffer in #3430
- Including Punctuation Marks by @BirdboyBolu in #3439
- feat: add support for
APP_CACHE_DIRandAPP_LOG_DIRby @drupol in #3518 - feat: add class magic methods to xml template, fix magic method return tag by @bshaffer in #3514
- Add callable rendering by @jaapio in #3538
- Feature/filesource tag by @jaapio in #3539
- feat: add magic flag to xml template by @bshaffer in #3520
Fixed
- fix: ensure uses/see/link descriptors render to string as expected by @bshaffer in #3244
- Fix OutputHello Example Param Wording by @CraicOverflow89 in #3324
- Fix issue with minimal directory by @jaapio in #3325
- Fix: remove redundant whitespace by @kudashevs in #3335
- Docker shouldn't run
help runby default by @mvriel in #3285 - Levenshtein argument too long by @mvriel in #3287
- References to cases are not linked by @mvriel in #3288
- Purge caches upon version change by @mvriel in #3289
- Extend timeout for UML generation to 20mins by @Hackwar in #3311
- Should fix #3415 by @peterhauke in #3441
- Resolve issue invalid property definition by @jaapio in #3479
- Bugfix/3494 ignore symlinks by @jaapio in #3495
Docs
- Start documenting pipelines and remove obsolete pipeline by @mvriel in #3483
- [DOCS] Link to configuration chapter by @linawolf in #3489
- [DOCS] Fix indentation to make code-blocks render by @linawolf in #3490
CI
- More strict argument check by @jaapio in #3195
- Reintroduce composer require checker by @jaapio in #3133
- Line numbers show 0 with InvalidTag issues by @mvriel in #3294
- Windows tests keep failing by @mvriel in #3295
- GH Actions: bust the cache semi-regularly by @jrfnl in #3357
- Start building on php 8.2 by @jaapio in #3376
- Use centralized phar build by @jaapio in #3529
- Comment use of unreleased method from ReflectionDocBlock by @mvriel in #3364
- Moved most parts of the DescriptorAbstract and TagDescriptor into traits by @mvriel in #3375
- Introduce CanHaveAType and CanHaveADefaultValue traits for Descriptors by @mvriel in #3379
Other
- Refactor LinkRenderer into a series of adapters and introduce references to guides by @mvriel in #3475
- Warn when multiple versions and/or sets of each type is given by @mvriel in #3477
- Move Files listing from Project to Documentation Sets by @mvriel in #3480
- Move indexes from Project to Documentation Sets by @mvriel in #3481
- Remove file and index getters and setters from project by @mvriel in #3482
- Extract pipeline for documentation set by @mvriel in #3485
- Collect files and indexes in API Documentation Set by @mvriel in #3486
- Cache per documentation set by @mvriel in #3487
- Move compiling into a pipeline by @mvriel in #3488
- Refactor all compilers to work on a DocumentationSet by @mvriel in #3492
- Change writers to be performed on a per-documentation-set basis by @mvriel in #3496
- Drop php 7.4 and php 8.0 by @jaapio in #3510
- Restructure compiler to allow different stages by @jaapio in #3519
- Php upgrade by @jaapio in #3540
- Chore: upgrade to symfony 6 by @jaapio in #3541
New Contributors
- @LeoVie made their first contribution in #3214
- @wouterj made their first contribution in #3218
- @bshaffer made their first contribution in #3244
- @amayer5125 made their first contribution in #3312
- @Hackwar made their first contribution in #3311
- @CraicOverflow89 made their first contribution in #3324
- @kudashevs made their first contribution in #3335
- @BirdboyBolu made their first contribution in #3439
- @peterhauke made their first contribution in #3441
- @linawolf made their first contribution in #3489
- @drupol made their first contribution in #3518
Full Changelog: v3.3.1...v3.4.0-rc
Contributors
Assets 3
v3.3.1
Fixed
- Refactor references out of the parser by @jaapio in #3135
- Add missing return type from method tags by @villfa in #3178
- Add Composer configuration allow-plugins by @villfa in #3185
- Update function signature to show return by reference by @villfa in #3187
- Add missing base url rendering by @ILL-DIE-TRYING in #3189
CI
New Contributors
Full Changelog: v3.3.0...v3.3.1
Contributors
Assets 4
v3.3.1 release candidate
Fixes:
- #3107 Defining constant in class method leads to parse error