feature #6944 Update doc about IDE file link format (nicolas-grekas)

xabbuh · xabbuh · commit f58526e27f73 · 2016-09-21T14:56:42.000+02:00
This PR was merged into the master branch. Discussion ---------- Update doc about IDE file link format todo: - [x] ~~tell about `kernel.file_link_format` parameter?~~ - [x] tell about prefix maps (see symfony/symfony#19807) Commits ------- f744396 Update doc about IDE file link format
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -204,21 +204,20 @@ ide
 
 **type**: ``string`` **default**: ``null``
 
-If you're using an IDE like TextMate or Mac Vim, then Symfony can turn all
-of the file paths in an exception message into a link, which will open that
-file in your IDE.
+Symfony can turn file paths seen in dumps and exception messages into links
+that will open in your preferred text editor or IDE.
 
-Symfony contains preconfigured URLs for some popular IDEs, you can set them
-using the following keys:
+Since every developer uses a different IDE, the recommended way to enable this
+feature is to configure it on a system level. This can be done by setting the
+``xdebug.file_link_format`` option in your ``php.ini`` configuration file.
 
-* ``textmate``
-* ``macvim``
-* ``emacs``
-* ``sublime``
+Alternatively, you can use this ``ide`` configuration key.
 
-You can also specify a custom URL string. If you do this, all percentage
-signs (``%``) must be doubled to escape that character. For example, if
-you use PHPstorm on the Mac OS platform, you will do something like:
+In both cases, the expected configuration value is a URL template that contains an
+``%f`` where the file path is expected and ``%l`` for the line number. When using
+the ``ide`` configuration key, percentages signs (``%``) must be escaped by
+doubling them. For example, if you use PHPstorm on the Mac OS platform, you will
+do something like:
 
 .. configuration-block::
 
@@ -250,16 +249,28 @@ you use PHPstorm on the Mac OS platform, you will do something like:
 
 .. tip::
 
-    If you're on a Windows PC, you can install the `PhpStormProtocol`_ to
-    be able to use this.
+    When running your app in a container or in a virtual machine, you can tell
+    Symfony to map files from the guest to the host by changing their prefix.
+    This map should be specified at the end of the URL template after a ``#``
+    using JSON-like key/values::
+
+        // /path/to/guest/.../file will be opened
+        // as /path/to/host/.../file on the host
+        // and /foo/.../file as /bar/.../file also
+        'myide://%f:%l#"/path/to/guest/":"/path/to/host/","/foo/":"/bar/"...'
+
+    .. versionadded:: 3.2
+        Guest to host mappings were introduced in Symfony 3.2.
+
+.. tip::
+
+    Symfony contains preconfigured URLs for some popular IDEs, you can set them
+    using the following values: ``textmate``, ``macvim``, ``emacs`` or ``sublime``.
 
-Of course, since every developer uses a different IDE, it's better to set
-this on a system level. This can be done by setting the ``xdebug.file_link_format``
-in the ``php.ini`` configuration to the URL string.
+.. tip::
 
-If you don't use Xdebug, another way is to set this URL string in the
-``SYMFONY__TEMPLATING__HELPER__CODE__FILE_LINK_FORMAT`` environment variable.
-If any of these configurations values are set, the ``ide`` option will be ignored.
+    If you're on a Windows PC, you can install the `PhpStormProtocol`_ to
+    be able to use this.
 
 .. _reference-framework-test:
 
