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

This RFC proposes adding support for 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 Twig, aspect-oriented programming frameworks such as GO-AOP, pre-processors such as YAY, source-code transformation tools such as 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.

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

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

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

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

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

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:

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

The same error message would now display as follows:

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

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

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

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)

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:

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

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

None.

Next PHP 7.x.

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

TODO: Will existing extensions be affected?

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

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.

TODO

TODO

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.

TODO

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

After the project is implemented, this section should contain

1. the version(s) it was merged to
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature

Links to external references, discussions or RFCs

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