====== Request for Comments: Line Markers in PHP ======
  * Version: 1.0
  * Date: 2011-08-11
  * Author: Gwynne Raskind <gwynne@php.net>
  * Status: Draft (Inactive)
  * First Published at: http://wiki.php.net/rfc/linecontrol


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.

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

Now, run the test:

<code>
$ 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
$
</code>

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

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

And then the result of running the test:

<code>
$ 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
$
</code>

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 ''<nowiki>__FILE__</nowiki>'' and ''<nowiki>__LINE__</nowiki>'' macros
  * Enables useful complex preprocessing

=== Con ===

  * Interferes with HTML mode?
  * Potential security implications for malicious manipulation of ''<nowiki>__FILE__</nowiki>''
  * Questionable interoperation with included files
  * May only be useful for CLI applications

==== Use cases ====

  - Preprocessors in the ''cpp(1)'' style.
  - Smarty compiled template files
  - PHPT tests
  - ''cat something.php | php -''
  - 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:

''# //linenum// "//filename//" //flags//''

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