Add "short name", "id", and "phid" variables for external editor URIs

Summary: Ref T13515. External editor URIs currently depend on repositories having callsigns, but callsigns are no longer required. Add some variables to support configuring this feature for repositories that do not have callsigns.

Test Plan: Changed settings to use new variables, saw links generate appropriately.

Maniphest Tasks: T13515

Differential Revision: https://secure.phabricator.com/D21147

src/applications/settings/setting/PhabricatorEditorSetting.php

@@ -26,7 +26,7 @@ final class PhabricatorEditorSetting
       "\n\n".
       "Provide a URI pattern for building external editor URIs in your ".
       "environment. For example, if you use TextMate on macOS, the pattern ".
-      "for your machine look like this:".
+      "for your machine may look something like this:".
       "\n\n".
       "```name=\"Example: TextMate on macOS\"\n".
       "%s\n".
@@ -36,7 +36,7 @@ final class PhabricatorEditorSetting
       "see **[[ %s | %s ]]**.".
       "\n\n".
       "See the tables below for a list of supported variables and protocols.",
-      'txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l',
+      'txmt://open/?url=file:///Users/alincoln/editor_links/%n/%f&line=%l',
       PhabricatorEnv::getDoclink('User Guide: Configuring an External Editor'),
       pht('User Guide: Configuring an External Editor'));
   }

src/docs/user/userguide/external_editor.diviner

@@ -6,8 +6,10 @@ Setting up an external editor to integrate with Diffusion and Differential.
 Overview
 ========
 
-You can configure a URI handler to allow you to open files from Differential
-and Diffusion in your preferred text editor.
+You can configure a URI handler to allow you to open files referenced in
+Differential and Diffusion in your preferred text editor on your local
+machine.
+
 
 Configuring Editors
 ===================
@@ -17,28 +19,60 @@ External Editor} and set "Editor Link" to a URI pattern (see below). This
 will enable an "Open in Editor" link in Differential, and an "Edit" button in
 Diffusion.
 
-In general, you'll set this field to something like:
+In general, you'll set this field to something like this, although the
+particular pattern to use depends on your editor and environment:
 
 ```lang=uri
 editor://open/?file=%f
 ```
 
+
+Mapping Repositories
+====================
+
+When you open a file in an external editor, Phabricator needs to be able to
+build a URI which includes the correct absolute path on disk to the local
+version of the file, including the repository directory.
+
+If all your repositories are named consistently in a single directory, you
+may be able to use the `%n` (repository short name) variable to do this.
+For example:
+
+```lang=uri
+editor://open/?file=/Users/alice/repositories/%n/%f
+```
+
+If your repositories aren't named consistently or aren't in a single location,
+you can build a local directory of symlinks which map a repositoriy identifier
+to the right location on disk:
+
+```
+/Users/alice/editor_links/ $ ls -l
+... search-service/ -> /Users/alice/backend/search/
+... site-templates/ -> /Users/alice/frontend/site/
+```
+
+Then use this directory in your editor URI:
+
+```lang=uri
+editor://open/?file=/Users/alice/editor_links/%n/%f
+```
+
+Instead of `%n` (repository short name), you can also use `%d` (repository ID)
+or `%p` (repository PHID). These identifiers are immutable and all repositories
+always have both identifiers, but they're less human-readable.
+
+
 Configuring: TextMate on macOS
 ==============================
 
 TextMate installs a `txmt://` handler by default, so it's easy to configure
 this feature if you use TextMate.
 
-First, create a local directory with symlinks for each repository callsign. For
-example, if you're developing Phabricator, it might look like this:
-
-  /Users/alincoln/editor_links/ $ ls -l
-  ... ARC -> /Users/alincoln/workspace/arcanist/
-  ... P -> /Users/alincoln/workspace/phabricator/
-  ... PHU -> /Users/alincoln/workspace/libphutil/
-
-Then set your "Editor Link" to:
+First, identify the parent directory where your repositories are stored
+(for example, `/Users/alice/repositories/`). Then, configure your editor
+pattern like this:
 
 ```lang=uri
-txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l
+txmt://open/?url=file:///Users/alice/repositories/%n/%f&line=%l
 ```

src/infrastructure/editor/PhabricatorEditorURIEngine.php

@@ -90,14 +90,6 @@ final class PhabricatorEditorURIEngine
 
   public static function getVariableDefinitions() {
     return array(
-      '%' => array(
-        'name' => pht('Literal Percent Symbol'),
-        'example' => '%',
-      ),
-      'r' => array(
-        'name' => pht('Repository Callsign'),
-        'example' => 'XYZ',
-      ),
       'f' => array(
         'name' => pht('File Name'),
         'example' => pht('path/to/source.c'),
@@ -106,6 +98,26 @@ final class PhabricatorEditorURIEngine
         'name' => pht('Line Number'),
         'example' => '777',
       ),
+      'n' => array(
+        'name' => pht('Repository Short Name'),
+        'example' => 'arcanist',
+      ),
+      'd' => array(
+        'name' => pht('Repository ID'),
+        'example' => '42',
+      ),
+      'p' => array(
+        'name' => pht('Repository PHID'),
+        'example' => 'PHID-REPO-abcdefghijklmnopqrst',
+      ),
+      'r' => array(
+        'name' => pht('Repository Callsign'),
+        'example' => 'XYZ',
+      ),
+      '%' => array(
+        'name' => pht('Literal Percent Symbol'),
+        'example' => '%',
+      ),
     );
   }
 
@@ -119,6 +131,9 @@ final class PhabricatorEditorURIEngine
 
     $variables = array(
       'r' => $this->escapeToken($repository->getCallsign()),
+      'n' => $this->escapeToken($repository->getRepositorySlug()),
+      'd' => $this->escapeToken($repository->getID()),
+      'p' => $this->escapeToken($repository->getPHID()),
     );
 
     return $this->newTokensWithVariables($tokens, $variables);