Request for Comments: Error message formatting for development

• Version: 1
• Date: 2011-07-26
• Author: Derick Rethans derick@php.net
• Status: Implemented in PHP 5.4
• Related RFCs: https://wiki.php.net/rfc/newinis

This RFC discusses the restoring of pre-PHP 5.3 functionality regarding the formatting of error messages. Prior to PHP 5.3, PHP had two bundled example .ini files: php.ini-dist and php.ini-recommended. In both cases the setting html_errors was not changed from PHP’s default (on). docref_root was left to “” (empty string).

In PHP 5.3 two new .ini files were introduced: php.ini-development and php.ini-production. In the latter, html_errors was changed from PHP’s internal default to off.

This RFC discussed the reversal of that change, so that html_errors is “on” by default again. It also suggests to only show documentation links if the docref_root setting is explicitly set to an HTTP path.

The html_errors setting is used in PHP to add HTML formatting around error messages in a web environment. It adds some mark-up and a link to the documentation as well. Some PHP extensions, such as Xdebug, enhance this mark-up to provide an outstanding development aid.

Most Linux distributions (if not all), force the use of php.ini-production, bundle that only variant or have php.ini-production as default. This means that for many users of such distributions the enhanced mark-up is no longer available by default, resulting in much confusion. Those distributions are just as much used for development as for production of course.

A few examples of confused people:

• http://cloudfysh.wordpress.com/2010/06/11/php-xdebug-not-formatting-var_dump/
• http://stackoverflow.com/questions/4534312/xdebug-var-dump-function-colors
• http://www.paoloiannelli.com/2011/04/15/solution-for-xdebug-not-overloading-var_dump/
• http://stackoverflow.com/questions/2108576/unreadable-var-dump-output-on-snow-leopard
• http://stackoverflow.com/questions/4678389/does-xdebug-beautify-var-dump

There is also a PHP bug report at https://bugs.php.net/bug.php?id=54537

It is also a FAQ for Xdebug: http://xdebug.org/docs/faq#format

In a development environment you would want this setting “on” to aid developing. In a production environment you rather have errors not showing up, but instead logged to a file. For that, you would set display_errors to “off” and log_errors=/tmp/php-errors.log. Because display_errors is already “off” in php.ini-production, the setting of html_errors to “on” has no effect, so it can quite safely be left “on” instead of the current practise of forcing it “off” in php.ini-production. Not seeing any errors showing up is easy to notice so it’s much clearer that display_errors needs to be set to “on” in those cases. The default PHP HTML marked-up errors hardly differ from the non-marked-up ones so in cases where Xdebug is not present, this does hardly show up.

The second thing to change is the way how the links to the documentation are shown whenever html_errors is set to “on”. Right now, they are always shown even if the docref_root setting is not set (empty string). The reason behind changing this is to de-couple the html_errors setting from documentation links behind shown. Allowing for more configurability and a better experience for the PHP developer.

A patch is available at: http://derickrethans.nl/files/dump/docref-20110623.diff.txt

• 2011-07-26: initial version for discussion
• 2011-08-03: opened voting
• 2011-08-10: closed voting, RFC accepted 16 for and 0 against, patch committed