====== PHP RFC: Add support for Sourcemaps ======

  * Version: 0.1
  * Date: 2016-04-06
  * Author: Rasmus Schultz <rasmus@mindplay.dk>
  * Status: Inactive
  * First Published at: http://wiki.php.net/rfc/sourcemaps

===== Introduction =====

This RFC proposes adding support for [[https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k|Source Map Revision 3]].

Source maps are an essential and familiar feature for developers using other web-specific technologies, most notably Javascript, SASS and LESS, and it is widely supported by major browsers, Node.js, various IDE families and many different tools.

Support for source maps under PHP on the server-side would benefit maintainers and consumers of many different PHP libraries that rely on some form of code generation, including template engines such as [[http://twig.sensiolabs.org/|Twig]], aspect-oriented programming frameworks such as [[https://github.com/goaop/framework|GO-AOP]], pre-processors such as [[https://github.com/marcioAlmada/yay|YAY]], source-code transformation tools such as [[https://github.com/grom358/pharborist|Pharborist]] and more.

One could envision support for source maps enabling more people to experiment with alterations to the language, such as prototyping and proofing RFCs before attempting a "real" implementation, and the ability to implement polyfills could mean that more developers are able and willing to adopt modern PHP features before they're widely available on hosted servers, and so forth.

===== Proposal =====

A generated ''.php'' file may ''declare'' the path to a matching source map file, relative to the location of the file itself - for example:

<code php>
<?php
declare(sourcemap_url='../../src/views/layout.twig.map');
</code>

Alternatively, the source map data may be embedded directly within the file:

<code php>
<?php
declare(sourcemap_data='eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGlzdC5qcyIsInNvdX.......');
</code>

The latter may be preferable for security reasons, while the former may be preferable e.g. for remote debugging.

====== Error Messages ======

Error messages, when referencing file-names, will take into account a source map, when present - for example, where a warning would otherwise display as follows:

<code>
Warning: Division by zero in /foo/layout.php on line 7
</code>

The same error message would now display as follows:

<code>
Warning: Division by zero in /foo/src/view/layout.twig on line 3 (/foo/layout.php on line 7)
</code>

E.g. displaying both the resolved source file-name and line number, as well as the PHP source file/line.

====== Stack Traces ======

The stack-trace from an uncaught Exception will display as follows:

<code>
Fatal error: Uncaught exception 'Exception' with message 'Division by zero' in /foo/src/bar.twig:71 ~ /foo/bar.php:56 
Stack trace:
#0 /foo/src/bar.twig(9) ~ /foo/bar.php(17): require()
#1 {main}
  thrown in /foo/src/bar.twig on line 71 (/foo/bar.php on line 56)
</code>

====== Exceptions ======

Uncaught Exceptions will cause an error-message and stack-trace print-out with file/line-references resolved and displayed, similarly to unhandled errors, as explained above.

The ''Exception'' class will have the following new properties and methods:

<code>
Exception {
    /* Properties */
    protected string|null $sourceFile ;
    protected int|null $sourceLine ;
    
    /* Methods */
    final public string|null getSourceFile ( void )
    final public int|null getSourceLine ( void )
}
</code>

Note that these methods and properties return ''null'' when no source map is available.

===== Backward Incompatible Changes =====

None.

===== Proposed PHP Version(s) =====

Next PHP 7.x.

===== RFC Impact =====

==== To SAPIs ====

TODO: Investigate and describe any impact to CLI, Development web server, embedded PHP etc.

==== To Existing Extensions ====

TODO: Will existing extensions be affected?

==== To Opcache ====

TODO: determine how this affects opcache. (most likely source maps need to be cached?)

==== php.ini Defaults ====

A new ''enable_source_maps'' setting will be added to ''php.ini'' - when set to ''0'', disabling the source map feature in favor of security, privacy and performance, since this is a developer feature.

This will be set to ''0'' by default, as well as in ''php.ini-production'' - it will be set to ''1'' in ''php.ini-development''.

Note that this setting disables automatic source map resolution in error-messages and stack-traces only. This setting does not affect the behavior of the ''Exception'' class methods and properties, which are always capable of reporting the source file/line if a source map is available - this enables developers to implement error logging/reporting facilities that make use of this information on-demand.

===== Open Issues =====

TODO 

===== Unaffected PHP Functionality =====

TODO

===== Future Scope =====

Perhaps in conjunction with this RFC, file and line-number references in error-message and stack-traces could be made consistent - a standard PHP stack-trace presently uses 3 (three!) different file/line-number formats.

===== Proposed Voting Choices =====

TODO

===== Patches and Tests =====

No patch exists at this time - the proposal is a draft, and as such is not ready for implementation.

===== Implementation =====
After the project is implemented, this section should contain 
  - the version(s) it was merged to
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
Links to external references, discussions or RFCs

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.