Fix several bugs and improve compatibility with newer Zend Framework versions

In version 2.7 there were a few fatal errors that happened in specific situations (as usual with bugs) and some changes were done to make integration with composer easier.

The most significant addition would be a new command line option --cache-folder with which you can tell phpDocumentor to write the cache files to a specific location. This is awesome if you want to keep your cache and docs separate or when setting up a Continuous Integration environment.

The second most interesting is the self-update command for the Phar installation for phpDocumentor. With this we follow in the footsteps of composer by adding the means to easily update your phar file an exchange it for a newer version of phpDocumentor.

What's next

A few days ago Mike van Riel posted a blog post (http://mikevanriel.com/entry/phpdocumentor-an-update) where he unveiled the changes that he is working on; combine that with the awesome contributions that we receive from the community means that interesting things are waiting on the horizon.

The changes that Mike is working on (which he lovingly dubbed Operation Blue Lightning) are meant to speed phpDocumentor up by a more than significant amount by refactoring some of the architecture of phpDocumentor. This will quite surely take more than the usual six weeks that we use per release and as such we will release version 2.9 as soon as Mike has finished his work on Blue Lightning.

Progress of this release can be tracked using a milestone that was created for this purpose: https://github.com/phpDocumentor/phpDocumentor2/milestones/Blue Lightning.

Happy hacking and until next time!

ADDED:     Argument "--cache-folder" to indicate where the cache is stored
ADDED:     `phpdoc self-update` command to the PHAR archive to update phpDocumentor with a single command
FIXED:     #423: Error report in responsive and responsive-twig template should hide empty results and update error counter next to the filename.
FIXED:     #573: Visibility filters in 'responsive' and 'responsive-twig' do not function properly
FIXED:     Several scrutinizer reported clean ups
FIXED:     If tmp was somewhere in path it would be incorrectly replaced
FIXED:     Several tests were added
FIXED:     It is now possible to install phpDocumentor using composer in a project using ZF 2.3 or higher
FIXED:     Fatal error: Call to a member function getParent() on a non-object in ConstantDescriptor.php
FIXED:     Fatal error: Call to a member function getParent() on a non-object in PropertyDescriptor.php
REMOVED:   Knp menu from composer.json because it was not used

Example tag, test coverage, bug fixes and improved Vagrant Setup

phpDocumentor version 2.7 is here. In this release we have fixed various issues that have been reported and thanks to an amazing Testfest in Amsterdam the Code Coverage has risen with at least 8%! A huge thanks to all who participated there.

In preparation for Testfest we have switched the provisioning of the development machines to use Ansible instead of puppet and made some parts optional (such as profiling and doc generation), making it a lot easier to use the virtual machine.

Something which is not reflected in the changelog below is that we have automated the deploys of the phpDocumentor website and the releases for phpDocumentor itself. In the past a release took several hours to prepare and execute, now we can do 75% of it within 15 minutes. I hope that we can automate the remaining bit as well but that is something for the future.

For a complete list of changes, see the changelog below and enjoy the new version!

ADDED:     A new writer that outputs a statistical extract from the collected data
ADDED:     Windows support for Ansible playbooks
ADDED:     8% to 10% Code Coverage thanks to #testfest 2014
ADDED:     #1347: Support for custom Vendor folders
ADDED:     Plugins can now be configured using parameters.
ADDED:     Complete support for @example
ADDED:     NamespacePrefix to LegacyNamespaceConverter plugin
FIXED:     Fatal error in MethodDescriptor when a parent was incorrectly called
FIXED:     Notice in '@see' handling
FIXED:     #1349: Configuration file was not found in working directory
FIXED:     Phing integration by re-instating the bootstrap class
FIXED:     Fixing type inference and variable length issues
FIXED:     Whether a method is inherited is shown again in XSL-based templates
FIXED:     Various minor bugs that became visible during the writing of tests
FIXED:     #1390: Source code paths were incorrect if the source was in folder
FIXED:     #1341: Icons in clean template were shown incorrectly
FIXED:     #1331: Not all validations were properly shown
FIXED:     #1077: Spaces in a path won't trip up libxml anymore
CHANGED:   Changed reference to deprecated Parsedown method parse() to text()
CHANGED:   Completely replaced Puppet with Ansible to provision contributor VMs
CHANGED:   Simpler provisioning for generic contributors; to do profiling
           another task is now needed
CHANGED:   Docs no longer refer to Short Description or Long Description but to
           Summary and Description per PSR-5

Hot-fix crashes

BREAKING: With 2.6.0 we inadvertently introduced crashes; here are the fixes!

FIXED:     #1330: Fix crash when assembling package tags
FIXED:     #1326: Fix crash while generating routes in Twig templates

v2.6.0: Improve tag support and resolve issues

ADDED:     #1087: Fully support `@see`
ADDED:     #1213: Resolve inline @see and @link to Markdown link
CHANGED:   #1186: Move checking of writer requirements
CHANGED:   #1267: XSL should use Router
CHANGED:   Update contribution guide to match new XHGUI
CHANGED:   #1248: Replace ZendConfig with Serializer-based config
CHANGED:   #1017: Updated help output for --hidden to be more descriptive
CHANGED:   #1264: Clean template no longer requires an internet connection
CHANGED:   #1212: Plugin configuration can now be loaded from a config file
CHANGED:   #1194: Add support for default parameter values in @method
FIXED:     #1313: Namespace Aliases are not stored on FileDescriptor
FIXED:     #1308: Multiple templates in configuration do not work
FIXED:     #713: XSL Templates are not found in Windows
FIXED:     #1253: Transformation crashes on typehint
FIXED:     #1268: Restore handling of visibility
FIXED:     #1130: Arrays not resolved in documentation
FIXED:     #1278: Template is not read from configuration
FIXED:     #1239: Parseprivate always triggers a complete parsing run
FIXED:     Parsing crashes on visibility as string
FIXED:     Routing crashes in Twig
FIXED:     #1307: Parsing crashes on unknown trait
FIXED:     #1114: Debug mode for Twig was not enabled
FIXED:     Errors were not shown in XSL templates
FIXED:     Remove duplicate namespace separator in constants defined by DEFINE
FIXED:     #930: @see and @link did not resolve self
FIXED:     #993: UTF-8 characters in filenames do not work in windows
FIXED:     #790: Inheritance in XSL was incorrectly registered
FIXED:     #713: Phar was sometimes not working on windows due to paths
FIXED:     Restore Behat tests
FIXED:     #1252: Namespaces are not shown on responsive template

Bugfixes

In the past few weeks our team has focused on fixing as many bugs as possible. We have managed to bring the list down significantly but unfortunately not all are included as they have been done in the last few days before this release.

But that only means there is something to look forward to!

Here is the list of changes in this release:

FIXED:     #1211: Loading a single plugin is not possible
FIXED:     #1232: Routing crashes on magic property in trait
FIXED:     #157: Classes do not inherit trait methods and props
FIXED:     #1193: Package tags don't inherit to classes
FIXED:     #1229: @method tag in a trait causes Exception
FIXED:     #1196: Some files cannot be copied with FileIO
CHANGED:   Better OPcache handling, annotations are not stripped anymore in PHP 5.5+
CHANGED:   phpdoc.php was renamed to phpdoc; phpdoc.php is kept for backwards compatibility

In addition to the above we managed to raise our code coverage to increase the stability of the application!

Have fun documenting!

Variadics and bug fixes

Another 6 weeks have passed, time for release 2.4!

These weeks go by faster than you'd expect; but in the mean time we haven't sat still at all. The main improvement for this release is that Variadics have been implemented and the Clean template now also features a shiny deprecated elements report.

And of course you haven't sat still as well. phpDocumentor is out there and used a lot, and as a result of that we receive new issue reports regularly which we try to fix as soon as we can.

All I can say is: keep them coming!

These issue reports help us to make phpDocumentor even more awesome than it already is (at least, we like to think so ;)).

Here is a complete changelog of the fixes and changes in the past period:

FIXED:     #1141: Deprecated report was missing in Clean template.
FIXED:     #1191: Opcache comments were not disabled due to incorrect extension name
FIXED:     #1184, #1181: @package tag on File was not recognized and not inherited on children
FIXED:     #1180: phpDocumentor crashes if an `@subpackage` has no name set
FIXED:     #1178: Generating a marker listing crashes sometimes
FIXED:     #1176: DocBlocks were not overridden on subclasses
FIXED:     #1163: Responsive and Responsive-twig templates do not work on HTTPS
FIXED:     #1158: Clean and Responsive template shows empty namespace menu when there are no namespaces
FIXED:     #1134, #1132: GraphViz reports can crash due to empty labels
FIXED:     #1098: Re-added missing Javascript file
FIXED:     #1037: IE did not like empty anchors
FIXED:     #152:  @internal and @ignore did not behave as expected
FIXED:     Javascript notices in Clean by upgrading jQuery
ADDED:     #1141: Deprecated report to the Clean template
ADDED:     #629:  Support for Variadics
CHANGED:   #1099, #1101: Replaced custom PHAR compiling with box-project.org and fixing issues in the mean time

Allowing composer installations to install with `stable`

There was an issue for some people using composer that running their update command failed because phpDocumentor depended on two unstable (dev) dependencies. With earlier releases this was necessary because of crippling bugs in released versions that were fixed in their master branch.

Both packages have tagged a new version and this release of phpDocumentor fixes the composer installation issue by using the most recently released version of those dependencies.

FIXED:     #1133: Fixed subpackage without package validation
FIXED:     #1120: Set stable versions of DOMPDF and ezcDocument in Composer.json

Add PDF processing, manuals and fixing several bugs

In this release we have implemented several fixes for bugs that were bugging you. Specifically issues with the way phpDocumentor inherits information have been fixed though there are still some remaining.

In addition to the above we have merged our sister-project Scrybe into phpDocumentor itself as a plugin. That means that starting with this release there is a foundation with which we can start working towards being a complete documentation solution, including reference material.

The Scrybe plugin is currently in alpha but is capable of transforming RestructuredText, and more formats in the future, to HTML and PDF documents. Let us know what you think of it but do expect quite a bit of bugs there; it is an early product.

Also have we started integrating DOMPDF and created a PDF writer with which PDF files can be generated from HTML output of phpDocumentor. Unfortunately there is no template yet, so it is not possible to use this new feature out of the box. We intend to add such a template in the future.

For a complete list of changes, see this list:

ADDED:     Support for writing PDF files using a Twig template by adding the PDF writer.
ADDED:     More documentation on types, running phpDocumentor, the @var tag.
ADDED:     Support for sorting lists with Twig and XSLT.
ADDED:     Basic support for generating reference documentation with ReST documents.
CHANGED:   Replaced custom phar building with the library from http://box-project.org.
FIXED:     #1090: GraphViz issues where the global namespace caused GraphViz not to generate.
FIXED:     #1037 by @siad007: if opcode cache is enabled for CLI then annotations are dropped.
FIXED:     #1031: Fixed inheritance for the summary, description, tags and the way @inheritdoc works.
FIXED:     Adding several unit tests.
FIXED:     Cleaned up code to remove warnings and errors.
FIXED:     #1111: An infinite loop occurred during processing of global constants.
FIXED:     Crash that occurred when building a tree of packages.
FIXED:     Crash that occurred when an interface was not recognized.
FIXED:     XSLTCache extension could not be used instead of XSLTProcessor due to a stray typehint.
FIXED:     #1110: Crash on incomplete `define` definition.
FIXED:     #949: `@inheritdoc` is not working with interfaces.

Important: we have not yet compiled a new PHAR file because there are issues in the PHAR generation process. We are working together with the lib maintainer to fix this issue but that means the PHAR is delayed for now.

More bug fixes and template touch-ups

This sprint was a bit of a slow period; we still got plenty of work done but more is always better!
Next sprint we expect to deliver a lot more features so keep tuned.

Do you think more could be fixed and have time to help with it? Please come over and help! We can use all the help we can get.

ADDED:     Information how to donate to phpDocumentor using gittip
ADDED:     Profiling information and process
CHANGED:   Moved the external class documentation code to their own router
CHANGED:   #1080: Replaced MarkDownExtra dependency with Parsedown
CHANGED:   Rewrote a lot of the documentation; still a work in progress
FIXED:     #720: External class documentation had ../files prepended
FIXED:     #932: Todo tags did not show up in Twig templates
FIXED:     #1049: Arguments passed by reference did not show up as being by reference
FIXED:     #1075: Prevent output from wrapping in Windows console
FIXED:     Cleaned up code based on Continuous Integration messages
FIXED:     Timezone issues on some machines
FIXED:     Various issues in several templates

Bug fixes and small features

With this release we have been able to provide a good number of patches for existing issues and some small features. Alas our core feature for this sprint, namely Search, is not stable enough be released. We will continue work on that during the 2.2 sprint.

If you discover any issues, do not hesitate and let us know using the issue tracker!

Below is a list of all changes in this release of phpDocumentor2:

ADDED:     New cli option 'log' to tell phpDocumentor the path where to log to
ADDED:     Verbosity can now be provided in three level, each indicating how much is written in the log
ADDED:     Support for the XSLCache drop in replacement of ext/xsl
ADDED:     Locale can now be supplied in the configuration
ADDED:     German translation for error messages
ADDED:     Support to insert Markdown files into specific points of the outputted documentation (partials)
ADDED:     Deprecated tag now registers the version number since when the associated element was deprecated
ADDED:     Show which traits are consumed by a class
ADDED:     Link to the traits that are consumed by a class
ADDED:     Show traits with their methods and properties
CHANGED:   phpDocumentor now checks for transformation requirements at the start of the application (#148)
FIXED:     Checkstyle error report only showed errors of the file itself and not subelements (#1046)
FIXED:     Validation to check for validity of return types
FIXED:     Validation to check for validity of parameters
FIXED:     Fatal error when a parent interface is not in the project
FIXED:     Template:list does not throw an error
FIXED:     XML output correctly exposes @see, @link, @version
FIXED:     XML output now does not choke on special characters
FIXED:     Error code for return type was incorrect
FIXED:     Functions in the responsive twig now unfold to show complete contents
FIXED:     Constants in the responsive twig now unfold to show complete contents
FIXED:     Using an ampersand in the type of an @param no longer causes a fatal (not a recommended practice!)
REMOVED:   #814; removed ParserAbstract base class for Parser
REMOVED:   PSR Draft is now moved to its own repo: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md
REMOVED:   Automatic generation of log files, the new log option can be used or a configuration option