rfc:linecontrol

Request for Comments: Line Markers in PHP

This RFC proposes to add linemarkers to PHP at the compiler level.

Introduction

Currently, anything which generates PHP from other input files of any kind must cope with the line numbers and file names in the resulting PHP file being potentially inaccurate.

Why is this needed?

Consider a scenario where a PHP script is only part of a larger file format, in this case PHPT.

--TEST--
Contrived example for an RFC.
--FILE--
<?php
This is a deliberate syntax error!
?>
--EXPECT--
Succulent delights.

Now, run the test:

$ TEST_PHP_EXECUTABLE=`which php` php run-tests.php ./contrived-test.phpt
...
$ cat ./contrived-test.log
...
---- ACTUAL OUTPUT
Parse error: syntax error, unexpected 'is' (T_STRING) in contrived-test.php on line 2
---- FAILED
$

This RFC would allow run-tests.php, in its PHPT parser, to output something like:

# 4 "./contrived-test.phpt"
<?php
...

And then the result of running the test:

$ TEST_PHP_EXECUTABLE=`which php` php run-tests.php ./contrived-test.phpt
...
$ cat ./contrived-test.log
...
---- ACTUAL OUTPUT
Parse error: syntax error, unexpected 'is' (T_STRING) in contrived-test.phpt on line 5
---- FAILED
$

The error message now locates the error much more usefully. The benefit is more obvious in larger files.

Pro/Con

Pro

  • Better identification of the location of error messages
  • More control over __FILE__ and __LINE__ macros
  • Enables useful complex preprocessing

Con

  • Interferes with HTML mode?
  • Potential security implications for malicious manipulation of __FILE__
  • Questionable interoperation with included files
  • May only be useful for CLI applications

Use cases

  1. Preprocessors in the cpp(1) style.
  2. Smarty compiled template files
  3. PHPT tests
  4. cat something.php | php -
  5. In general, anything which may produce error-emitting PHP code whose source is not immediately accessible.

Proposal

The proposed syntax for linemarkers is identical to that used by the cpp(1) command included with GCC:

# linenumfilenameflags

Alternatively, #line could be used instead of a simple #.

The flags field has the following potential values:

1 - Indicates the start of a new file.

2 - Indicates the return to a file after having switched to another.

This syntax has the advantage of being 100% backward-compatible with earlier versions of PHP, as the # will be interpreted as starting a one-line comment.

Line markers which exist outside of <?php ?> tags should be considered part of the enclosing HTML/XML and ignored as with all other such content.

Patch

No patch has been written yet, pending a determination of feasability and desirability.

Changelog

  • 2011-08-11: Initial revision
rfc/linecontrol.txt · Last modified: 2014/04/09 00:51 by levim