Update aliases example file and fix up alias usage (#3010)

- Make sure site-aliases directory is considered in alias search path.
- Remove documentation for remote aliases w/out root / uri - no longer supported
- Rename runtime.context.alias-path to drush.paths.alias-path.
- Add support for evaluation in configuration items, e.g. ${env.home}

composer.json

@@ -28,11 +28,11 @@
     "psr/log": "~1.0",
     "psy/psysh": "~0.6",
     "league/container": "~2",
-    "consolidation/config": "dev-master",
+    "consolidation/config": "^1.0.3",
     "consolidation/robo": "^1.1.2",
     "symfony/config": "~2.2|^3",
     "chi-teck/drupal-code-generator": "^1.17.3",
-    "consolidation/annotated-command": "dev-master as 2.7.0",
+    "consolidation/annotated-command": "^2.7.1",
     "consolidation/output-formatters": "^3.1.11",
     "grasmash/yaml-expander": "^1.1.1",
     "symfony/yaml": "~2.3|^3",

examples/example.aliases.yml

@@ -1,15 +1,23 @@
-
+#
 # Example of valid statements for an alias file.
 #
 # Use this file as a guide to creating your own aliases.
 #
 # Aliases are commonly used to define short names for
 # local or remote Drupal installations; however, an alias
 # is really nothing more than a collection of options.
-# A canonical alias named "dev" that points to a local
+#
+# Drush site aliases always contain one or more environments;
+# for example, a site may have "dev", "test" and "live"
+# environments. The default environment is "dev"; the dev
+# environment of a site named "example" may therefore be
+# referred to as either "@example.dev" or "@example".
+#
+# A canonical alias named "example" that points to a local
 # Drupal site named "http://example.com" looks like this:
 #
 # @code
+# File: example.alias.yml
 # dev:
 #   root: /path/to/drupal
 #   uri: http://example.com
@@ -18,13 +26,13 @@
 # With this alias definition, then the following commands
 # are equivalent:
 #
-#   $ drush @dev status
+#   $ drush @example status
 #   $ drush --root=/path/to/drupal --uri=http://example.com status
 #
 # See the --uri option documentation below for hints on setting its value.
 #
 # Any option that can be placed on the Drush commandline
-# can also appear in an alias definition.
+# can also appear in an alias definition inside an 'options' section.
 #
 # There are several ways to create alias files.
 #
@@ -36,80 +44,88 @@
 # the alias search path.  The following locations are examined
 # for alias files:
 #
-#   1. In any path set in runtime.context in drush.yml
+#   1. In any path set in drush.alias-path in drush.yml
 #      or (equivalently) any path passed in via --alias-path=...
 #      on the command line.
 #   2. In one of the site-specific locations:
 #        a. The /drush and /sites/all/drush folders for the current Drupal site
 #        b. The /drush folder in the directory above the current Drupal site
 #
-# These locations are searched recursively.  If there is a folder called
-# 'site-aliases' in any search path, then Drush will search for site aliases
-# only inside that directory.
+# These locations are no longer searched recursively; alias files must
+# appear directly inside one of the search locations, or in a directory called
+# 'site-aliases' in a search location, or it will not be found.
 #
 # The preferred locations for alias files, then, are:
 #
 #   $ROOT/drush/site-aliases
 #   $ROOT/sites/all/drush/site-aliases
 #   $ROOT/../drush/site-aliases
 #
-# Files stored in these locations can be used to create aliases
-# to local and remote Drupal installations.  These aliases can be
-# used in place of a site specification on the command line, and
-# may also be used in arguments to certain commands such as
-# "drush rsync" and "drush sql-sync".
+# If you would like to add additional locations, you can do so by
+# listing additional locations in your configuraton files. For example,
+# to re-add the default user alias path from Drush 8, put the following
+# in your ~/.drush/drush.yml configuration file:
+#
+# @code
+# drush:
+#   paths:
+#     alias-path:
+#       - '${env.home}/.drush/site-aliases'
+#       - /etc/drush
+# @endcode
+#
+# Files stored in one of the search path locations can be used to create
+# aliases to local and remote Drupal installations.  These aliases can be
+# used in place of a site specification on the command line, and may also
+# be used in arguments to certain commands such as "drush rsync" and
+# "drush sql:sync".
 #
 # Alias groups (aliases stored together in files called
-# GROUPNAME.aliases.yml, as mentioned above) create an implicit
-# namespace that is named after the group name.
+# GROUPNAME.aliases.yml can be used to collect related sites
+# together.
 #
 # For example:
 #
 # @code
-# # File: mysite.aliases.yml
-# dev:
-#   root: /path/to/drupal
-#   uri: https://dev.example.com
-# live:
-#   root: /other/path/to/drupal
-#   uri: https://live.example.com
+# # File: elements.aliases.yml
+# sites:
+#   earth:
+#     dev:
+#       root: /path/to/drupal-earth
+#       uri: https://dev.earth.com
+#     live:
+#       root: /other/path/to/drupal-earth
+#       uri: https://earth.com
+#   wind:
+#     dev:
+#       root: /path/to/drupal-wind
+#       uri: https://dev.wind.com
+#     live:
+#       root: /other/path/to/drupal-wind
+#       uri: https://earth.com
 # @endcode
 #
 # Then the following aliases are defined:
-# - @mysite.dev
-# - @mysite.live
+# - @elements.earth.dev
+# - @elements.earth.live
+# - @elements.wind.dev
+# - @elements.wind.live
 #
 # To see an example alias definition for the current bootstrapped
-# site, use the "site-alias" command with the built-in alias "@self":
+# site, use the "site:alias" command with the built-in alias "@self":
 #
-#   $ drush site-alias @self
+#   $ drush site:alias @self
 #
 # Drush also supports *remote* site aliases.  When a site alias is
 # defined for a remote site, Drush will use the ssh command to run
 # the requested command on the remote machine.  The simplest remote
 # alias looks like this:
 #
 # @code
+# # File: remote.alias.yml
 # live:
-#   remote-host: server.domain.com
-#   remote-user: www-admin
-# @endcode
-#
-# The form above requires that Drush be installed on the remote machine,
-# and that there also be an alias of the same name defined on that
-# machine.  The remote alias should define the 'root' and 'uri' elements,
-# as shown in the initial example at the top of this file.
-#
-# If you do not wish to maintain site aliases on the remote machine,
-# then you may define an alias that contains all of the elements
-# 'remote-host', 'remote-user', 'root' and 'uri'.  If you do this, then
-# Drush will make the remote call using the --root and --uri options
-# to identify the site, so no site alias is required on the remote server.
-#
-# @code
-# live:
-#   remote-host: server.domain.com
-#   remote-user: www-admin
+#   host: server.domain.com
+#   user: www-admin
 #   root: /other/path/to/drupal
 #   uri: http://example.com
 # @endcode
@@ -119,8 +135,8 @@
 #
 #   $ drush @none status
 #
-# See `drush help site-alias` for more options for displaying site
-# aliases.  See `drush topic docs-bastion` for instructions on configuring
+# See `drush help site:alias` for more options for displaying site
+# aliases.  See `drush topic docs:bastion` for instructions on configuring
 # remote access to a Drupal site behind a firewall via a bastion server.
 #
 # Although most aliases will contain only a few options, a number
@@ -129,12 +145,12 @@
 # - 'uri': The value of --uri should always be the same as
 #   when the site is being accessed from a web browser (e.g. http://example.com)
 # - 'root': The Drupal root; must not be specified as a relative path.
-# - 'remote-host': The fully-qualified domain name of the remote system
+# - 'host': The fully-qualified domain name of the remote system
 #   hosting the Drupal instance. **Important Note: The remote-host option
 #   must be omitted for local sites, as this option controls various
 #   operations, such as whether or not rsync parameters are for local or
 #   remote machines, and so on. @see hook_drush_sitealias_alter() in drush.api.php
-# - 'remote-user': The username to log in as when using ssh or rsync.
+# - 'user': The username to log in as when using ssh or rsync.
 # - 'os': The operating system of the remote server.  Valid values
 #   are 'Windows' and 'Linux'. Be sure to set this value for all remote
 #   aliases because the default value is PHP_OS if 'remote-host'
@@ -146,57 +162,50 @@
 #   standard port, alternative identity file, or alternative
 #   authentication method, ssh-options can contain a string of extra
 #   options that are used with the ssh command, eg "-p 100"
-# - 'path-aliases': An array of aliases for common rsync targets.
+# - 'paths': An array of aliases for common rsync targets.
 #   Relative aliases are always taken from the Drupal root.
-#   - '%drush-script': The path to the 'drush' script, or to 'drush.php'.
-#     This is used by backend invoke when drush
-#     runs a drush command.  The default is 'drush' on remote machines, or
-#     the full path to drush.php on the local machine.
-#   - '%drush': A read-only property: points to the folder that the drush
-#     script is stored in.
-#   - '%files': Path to 'files' directory.  This will be looked up if not
+#   - 'files': Path to 'files' directory.  This will be looked up if not
 #     specified.
-#   - '%root': A reference to the Drupal root defined in the 'root' item in the
-#     site alias record.
-# - 'php': path to custom php interpreter.
-# - 'php-options': commandline options for php interpreter, you may
-#   want to set this to '-d error_reporting="E_ALL^E_DEPRECATED"'
-# - 'command-specific': These options will only be set if the alias
+# - 'command': These options will only be set if the alias
 #   is used with the specified command.  In the example below, the option
 #   `--no-dump` will be selected whenever the @stage alias
 #   is used in any of the following ways:
-#   - `drush @stage sql-sync @self @live`
-#   - `drush sql-sync @stage @live`
-#   - `drush sql-sync @live @stage`
-# - '#peer': Settings that begin with a '#' are not used directly by Drush, and
-#   in fact are removed before making a backend invoke call (for example).
-#   These kinds of values are useful in conjunction with shell aliases.  See
-#   `drush topic docs-shell-aliases` for more information on this.
-# - '#env-vars': An associative array of keys and values that should be set on
-#    the remote side before invoking drush.
+#     - `drush @stage sql-sync @self @live`
+#     - `drush sql-sync @stage @live`
+#     - `drush sql-sync @live @stage`
+#   NOTE: Setting boolean options broke with Symfony 3. This will be fixed
+#     in a future release. See: https://github.com/drush-ops/drush/issues/2956
 #
 # Altering aliases:
 #
 # It is no longer possible to alter aliases dynamically. This is a planned feature. Help wanted.
 #
-# Some examples appear below.  Remove the leading hash signs to enable.
-#stage:
-#  uri: http://stage.example.com
-#  root: /path/to/remote/drupal/root
-#  remote-host: mystagingserver.myisp.com
-#  remote-user: publisher
-#  os: Linux
-#  path-aliases:
-#    - %drush-script: path/to/drush/drush
-#    - %files: sites/mydrupalsite.com/files
-#    - %custom: /my/custom/path
-#  command-specific:
-#     sql-sync:
-#       options:
-#         no-dump: true
-#
-#dev:
-#  root: /path/to/docroot
-#  uri: https://dev.example.com
-#
-#
+# Environment variables:
+#
+# It is no longer possible to set environment variables from within an alias.
+# This is also a planned feature.
+#
+# An example appears below. Edit to suit and remove the @code / @endcode and
+# leading hashes to enable.
+#
+# @code
+# # File: mysite.alias.yml
+# stage:
+#   uri: http://stage.example.com
+#   root: /path/to/remote/drupal/root
+#   host: mystagingserver.myisp.com
+#   user: publisher
+#   os: Linux
+#   paths:
+#    - files: sites/mydrupalsite.com/files
+#    - custom: /my/custom/path
+#   command:
+#     sql:
+#       sync:
+#         options:
+#           no-dump: true
+# dev:
+#   root: /path/to/docroot
+#   uri: https://dev.example.com
+# @endcode
+#

includes/backend.inc

@@ -744,7 +744,10 @@ function drush_backend_invoke_concurrent($invocations, $common_options = array()
     // $command_options += drush_command_get_command_specific_options($site_record, $command);
 
     // Add in preflight option contexts (--include et. al)
-    $preflightContextOptions = \Drush\Drush::config()->get(PreflightArgs::DRUSH_CONFIG_CONTEXT_NAMESPACE, []);
+    $preflightContextOptions =
+      \Drush\Drush::config()->get(PreflightArgs::DRUSH_RUNTIME_CONTEXT_NAMESPACE, []) +
+      \Drush\Drush::config()->get(PreflightArgs::DRUSH_CONFIG_PATH_NAMESPACE, []);
+    $preflightContextOptions['local'] = \Drush\Drush::config()->get('runtime.local', false);
     foreach ($preflightContextOptions as $key => $value) {
       if ($value) {
         $command_options[$key] = $value;

isolation/.gitignore

@@ -1 +1,2 @@
 vendor
+build

isolation/fixtures/sites/d8/drush/site-aliases/elements.aliases.yml

@@ -0,0 +1,15 @@
+sites:
+  earth:
+    dev:
+      root: /path/to/drupal-earth
+      uri: https://dev.earth.com
+    live:
+      root: /other/path/to/drupal-earth
+      uri: https://earth.com
+  wind:
+    dev:
+      root: /path/to/drupal-wind
+      uri: https://dev.wind.com
+    live:
+      root: /other/path/to/drupal-wind
+      uri: https://earth.com

isolation/tests/ConfigLocatorTest.php

@@ -15,7 +15,7 @@ class ConfigLocatorTest extends TestCase
      */
     function testOnlyEnvironmentData()
     {
-        $configLocator = new ConfigLocator();
+        $configLocator = new ConfigLocator('TEST_');
         $configLocator->addEnvironment($this->environment());
         $config = $configLocator->config();
         $this->assertEquals($this->homeDir(), $config->get('env.cwd'));
@@ -26,7 +26,7 @@ function testOnlyEnvironmentData()
      */
     function testLoadAll()
     {
-        $configLocator = $this->createConfigLoader();
+        $configLocator = $this->createConfigLocator();
 
         $sources = $configLocator->sources();
         //$this->assertEquals('environment', $sources['env']['cwd']);
@@ -52,7 +52,7 @@ function testLoadAll()
      */
     function testLocalMode()
     {
-        $configLocator = $this->createConfigLoader(true);
+        $configLocator = $this->createConfigLocator(true);
 
         /*
         $sources = $configLocator->sources();
@@ -69,12 +69,28 @@ function testLocalMode()
         $this->assertEquals('A site-specific setting', $config->get('test.site'));
     }
 
+    function testAliasPaths()
+    {
+        $configLocator = $this->createConfigLocator();
+        $aliasPaths = $configLocator->getSiteAliasPaths(['/home/user/aliases'], $this->environment());
+        $aliasPaths = array_map(
+            function ($item) {
+                return str_replace(dirname(__DIR__) . '/', '', $item);
+            },
+            $aliasPaths
+        );
+        sort($aliasPaths);
+
+        $expected = 'fixtures/sites/d8/drush,fixtures/sites/d8/drush/site-aliases';
+        $this->assertEquals($expected, implode(',', $aliasPaths));
+    }
+
     /**
      * Create a config locator from All The Sources, for use in multiple tests.
      */
-    protected function createConfigLoader($isLocal = false, $configPath = '', $aliasPath = '', $alias = '')
+    protected function createConfigLocator($isLocal = false, $configPath = '')
     {
-        $configLocator = new ConfigLocator();
+        $configLocator = new ConfigLocator('TEST_');
         $configLocator->collectSources();
         $configLocator->setLocal($isLocal);
         $configLocator->addUserConfig([$configPath], $this->environment()->systemConfigPath(), $this->environment()->userConfigPath());