Change default preferred-install to dist, add --prefer-install=auto|dist|source to allow specifying auto (#9603)

Fixes #9546
Fixes #9674

doc/03-cli.md

@@ -84,17 +84,14 @@ resolution.
 
 ### Options
 
-* **--prefer-source:** There are two ways of downloading a package: `source`
+* **--prefer-install:** There are two ways of downloading a package: `source`
-  and `dist`. For stable versions Composer will use the `dist` by default.
+  and `dist`. Composer uses `dist` by default. If you pass
-  The `source` is a version control repository. If `--prefer-source` is
+  `--prefer-install=source` (or `--prefer-source`) Composer will install from
-  enabled, Composer will install from `source` if there is one. This is
+  `source` if there is one. This is useful if you want to make a bugfix to a
-  useful if you want to make a bugfix to a project and get a local git
+  project and get a local git clone of the dependency directly.
-  clone of the dependency directly.
+  To get the legacy behavior where Composer use `source` automatically for dev
-* **--prefer-dist:** Reverse of `--prefer-source`, Composer will install
+  versions of packages, use `--prefer-install=auto`. See also [config.preferred-install](06-config.md#preferred-install).
-  from `dist` if possible. This can speed up installs substantially on build
+  Passing this flag will override the config value.
-  servers and other use cases where you typically do not run updates of the
-  vendors. It is also a way to circumvent problems with git if you do not
-  have a proper setup.
 * **--dry-run:** If you want to run through an installation without actually
   installing a package, you can use `--dry-run`. This will simulate the
   installation and show you what would happen.
@@ -169,8 +166,14 @@ php composer.phar update vendor/package:2.0.1 vendor/package2:3.0.*
 
 ### Options
 
-* **--prefer-source:** Install packages from `source` when available.
+* **--prefer-install:** There are two ways of downloading a package: `source`
-* **--prefer-dist:** Install packages from `dist` when available.
+  and `dist`. Composer uses `dist` by default. If you pass
+  `--prefer-install=source` (or `--prefer-source`) Composer will install from
+  `source` if there is one. This is useful if you want to make a bugfix to a
+  project and get a local git clone of the dependency directly.
+  To get the legacy behavior where Composer use `source` automatically for dev
+  versions of packages, use `--prefer-install=auto`. See also [config.preferred-install](06-config.md#preferred-install).
+  Passing this flag will override the config value.
 * **--dry-run:** Simulate the command without actually doing anything.
 * **--dev:** Install packages listed in `require-dev` (this is the default behavior).
 * **--no-dev:** Skip installing packages listed in `require-dev`. The autoloader generation skips the `autoload-dev` rules.
@@ -232,8 +235,14 @@ If you do not specify a package, composer will prompt you to search for a packag
 
 * **--dev:** Add packages to `require-dev`.
 * **--dry-run:** Simulate the command without actually doing anything.
-* **--prefer-source:** Install packages from `source` when available.
+* **--prefer-install:** There are two ways of downloading a package: `source`
-* **--prefer-dist:** Install packages from `dist` when available.
+  and `dist`. Composer uses `dist` by default. If you pass
+  `--prefer-install=source` (or `--prefer-source`) Composer will install from
+  `source` if there is one. This is useful if you want to make a bugfix to a
+  project and get a local git clone of the dependency directly.
+  To get the legacy behavior where Composer use `source` automatically for dev
+  versions of packages, use `--prefer-install=auto`. See also [config.preferred-install](06-config.md#preferred-install).
+  Passing this flag will override the config value.
 * **--no-progress:** Removes the progress display that can mess with some
   terminals or scripts which don't handle backspace characters.
 * **--no-update:** Disables the automatic update of the dependencies (implies --no-install).
@@ -745,8 +754,14 @@ By default the command checks for the packages on packagist.org.
 ### Options
 
 * **--stability (-s):** Minimum stability of package. Defaults to `stable`.
-* **--prefer-source:** Install packages from `source` when available.
+* **--prefer-install:** There are two ways of downloading a package: `source`
-* **--prefer-dist:** Install packages from `dist` when available.
+  and `dist`. Composer uses `dist` by default. If you pass
+  `--prefer-install=source` (or `--prefer-source`) Composer will install from
+  `source` if there is one. This is useful if you want to make a bugfix to a
+  project and get a local git clone of the dependency directly.
+  To get the legacy behavior where Composer use `source` automatically for dev
+  versions of packages, use `--prefer-install=auto`. See also [config.preferred-install](06-config.md#preferred-install).
+  Passing this flag will override the config value.
 * **--repository:** Provide a custom repository to search for the package,
   which will be used instead of packagist. Can be either an HTTP URL pointing
   to a `composer` repository, a path to a local `packages.json` file, or a

doc/06-config.md

@@ -31,7 +31,7 @@ in the PHP include path.
 
 ## preferred-install
 
-Defaults to `auto` and can be any of `source`, `dist` or `auto`. This option
+Defaults to `dist` and can be any of `source`, `dist` or `auto`. This option
 allows you to set the install method Composer will prefer to use. Can
 optionally be a hash of patterns for more granular install preferences.
 
@@ -48,6 +48,16 @@ optionally be a hash of patterns for more granular install preferences.
 }
 ```
 
+- `source` means Composer will install packages from their `source` if there
+  is one. This is typically a git clone or equivalent checkout of the version
+  control system the package uses. This is useful if you want to make a bugfix
+  to a project and get a local git clone of the dependency directly.
+- `auto` is the legacy behavior where Composer uses `source` automatically
+  for dev versions, and `dist` otherwise.
+- `dist` (the default as of Composer 2.1) means Composer installs from `dist`,
+  where possible. This is typically a zip file download, which is faster than
+  cloning the entire repository.
+
 > **Note:** Order matters. More specific patterns should be earlier than
 > more relaxed patterns. When mixing the string notation with the hash
 > configuration in global and package configurations the string notation

src/Composer/Command/BaseCommand.php

@@ -175,6 +175,29 @@ abstract class BaseCommand extends Command
                 break;
         }
 
+        if ($input->hasOption('prefer-install') && $input->getOption('prefer-install')) {
+            if ($input->getOption('prefer-source')) {
+                throw new \InvalidArgumentException('--prefer-source can not be used together with --prefer-install');
+            }
+            if ($input->getOption('prefer-dist')) {
+                throw new \InvalidArgumentException('--prefer-dist can not be used together with --prefer-install');
+            }
+            switch ($input->getOption('prefer-install')) {
+                case 'dist':
+                    $input->setOption('prefer-dist', true);
+                    break;
+                case 'source':
+                    $input->setOption('prefer-source', true);
+                    break;
+                case 'auto':
+                    $preferDist = false;
+                    $preferSource = false;
+                    break;
+                default:
+                    throw new \UnexpectedValueException('--prefer-install accepts one of "dist", "source" or "auto", got '.$input->getOption('prefer-install'));
+            }
+        }
+
         if ($input->getOption('prefer-source') || $input->getOption('prefer-dist') || ($keepVcsRequiresPreferSource && $input->hasOption('keep-vcs') && $input->getOption('keep-vcs'))) {
             $preferSource = $input->getOption('prefer-source') || ($keepVcsRequiresPreferSource && $input->hasOption('keep-vcs') && $input->getOption('keep-vcs'));
             $preferDist = (bool) $input->getOption('prefer-dist');

src/Composer/Command/CreateProjectCommand.php

@@ -66,7 +66,8 @@ class CreateProjectCommand extends BaseCommand
                 new InputArgument('version', InputArgument::OPTIONAL, 'Version, will default to latest'),
                 new InputOption('stability', 's', InputOption::VALUE_REQUIRED, 'Minimum-stability allowed (unless a version is specified).'),
                 new InputOption('prefer-source', null, InputOption::VALUE_NONE, 'Forces installation from package sources when possible, including VCS information.'),
-                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist even for dev versions.'),
+                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist (default behavior).'),
+                new InputOption('prefer-install', null, InputOption::VALUE_REQUIRED, 'Forces installation from package dist|source|auto (auto chooses source for dev versions, dist for the rest).'),
                 new InputOption('repository', null, InputOption::VALUE_REQUIRED | InputOption::VALUE_IS_ARRAY, 'Add custom repositories to look the package up, either by URL or using JSON arrays'),
                 new InputOption('repository-url', null, InputOption::VALUE_REQUIRED, 'DEPRECATED: Use --repository instead.'),
                 new InputOption('add-repository', null, InputOption::VALUE_NONE, 'Add the custom repository in the composer.json. If a lock file is present it will be deleted and an update will be run instead of install.'),

src/Composer/Command/InstallCommand.php

@@ -37,7 +37,8 @@ class InstallCommand extends BaseCommand
             ->setDescription('Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json.')
             ->setDefinition(array(
                 new InputOption('prefer-source', null, InputOption::VALUE_NONE, 'Forces installation from package sources when possible, including VCS information.'),
-                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist even for dev versions.'),
+                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist (default behavior).'),
+                new InputOption('prefer-install', null, InputOption::VALUE_REQUIRED, 'Forces installation from package dist|source|auto (auto chooses source for dev versions, dist for the rest).'),
                 new InputOption('dry-run', null, InputOption::VALUE_NONE, 'Outputs the operations but will not execute anything (implicitly enables --verbose).'),
                 new InputOption('dev', null, InputOption::VALUE_NONE, 'DEPRECATED: Enables installation of require-dev packages (enabled by default, only present for BC).'),
                 new InputOption('no-suggest', null, InputOption::VALUE_NONE, 'DEPRECATED: This flag does not exist anymore.'),

src/Composer/Command/RequireCommand.php

@@ -57,7 +57,8 @@ class RequireCommand extends InitCommand
                 new InputOption('dev', null, InputOption::VALUE_NONE, 'Add requirement to require-dev.'),
                 new InputOption('dry-run', null, InputOption::VALUE_NONE, 'Outputs the operations but will not execute anything (implicitly enables --verbose).'),
                 new InputOption('prefer-source', null, InputOption::VALUE_NONE, 'Forces installation from package sources when possible, including VCS information.'),
-                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist even for dev versions.'),
+                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist (default behavior).'),
+                new InputOption('prefer-install', null, InputOption::VALUE_REQUIRED, 'Forces installation from package dist|source|auto (auto chooses source for dev versions, dist for the rest).'),
                 new InputOption('fixed', null, InputOption::VALUE_NONE, 'Write fixed version to the composer.json.'),
                 new InputOption('no-suggest', null, InputOption::VALUE_NONE, 'DEPRECATED: This flag does not exist anymore.'),
                 new InputOption('no-progress', null, InputOption::VALUE_NONE, 'Do not output download progress.'),
@@ -354,12 +355,13 @@ EOT
         $install = Installer::create($io, $composer);
 
         $ignorePlatformReqs = $input->getOption('ignore-platform-reqs') ?: ($input->getOption('ignore-platform-req') ?: false);
+        list($preferSource, $preferDist) = $this->getPreferredInstallOptions($composer->getConfig(), $input);
 
         $install
             ->setDryRun($input->getOption('dry-run'))
             ->setVerbose($input->getOption('verbose'))
-            ->setPreferSource($input->getOption('prefer-source'))
+            ->setPreferSource($preferSource)
-            ->setPreferDist($input->getOption('prefer-dist'))
+            ->setPreferDist($preferDist)
             ->setDevMode($updateDevMode)
             ->setRunScripts(!$input->getOption('no-scripts'))
             ->setOptimizeAutoloader($optimize)

src/Composer/Command/UpdateCommand.php

@@ -45,7 +45,8 @@ class UpdateCommand extends BaseCommand
                 new InputArgument('packages', InputArgument::IS_ARRAY | InputArgument::OPTIONAL, 'Packages that should be updated, if not provided all packages are.'),
                 new InputOption('with', null, InputOption::VALUE_IS_ARRAY | InputOption::VALUE_REQUIRED, 'Temporary version constraint to add, e.g. foo/bar:1.0.0 or foo/bar=1.0.0'),
                 new InputOption('prefer-source', null, InputOption::VALUE_NONE, 'Forces installation from package sources when possible, including VCS information.'),
-                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist even for dev versions.'),
+                new InputOption('prefer-dist', null, InputOption::VALUE_NONE, 'Forces installation from package dist (default behavior).'),
+                new InputOption('prefer-install', null, InputOption::VALUE_REQUIRED, 'Forces installation from package dist|source|auto (auto chooses source for dev versions, dist for the rest).'),
                 new InputOption('dry-run', null, InputOption::VALUE_NONE, 'Outputs the operations but will not execute anything (implicitly enables --verbose).'),
                 new InputOption('dev', null, InputOption::VALUE_NONE, 'DEPRECATED: Enables installation of require-dev packages (enabled by default, only present for BC).'),
                 new InputOption('no-dev', null, InputOption::VALUE_NONE, 'Disables installation of require-dev packages.'),

src/Composer/Config.php

@@ -28,7 +28,7 @@ class Config
     public static $defaultConfig = array(
         'process-timeout' => 300,
         'use-include-path' => false,
-        'preferred-install' => 'auto',
+        'preferred-install' => 'dist',
         'notify-on-install' => true,
         'github-protocols' => array('https', 'ssh', 'git'),
         'vendor-dir' => 'vendor',