README

插件目的

magento/composer-root-update-plugin Composer插件在更新到新版本的Magento产品需求之前，解决了需要修改根项目composer.json文件的变化。

这是通过比较当前安装中对应于当前安装的Magento版本和版本的Magento项目的根composer.json文件，与当运行composer require命令时的目标Magento产品或云元包的Magento项目composer.json文件来实现的。如果这两个文件之间没有冲突，则应用在两个文件之间找到的任何变化。

入门

系统要求

magento/composer-root-update-plugin包需要Composer版本1.10.19或更早版本，或版本2.0.0 - 2.0.8。将测试与较新版本的Composer的兼容性，并在未来的插件版本中添加。

安装

要安装插件，请在Magento根目录中运行以下命令。

composer require magento/composer-root-update-plugin ~1.1 --no-update
composer update 

用法

当需要新的Magento产品或云元包时，该插件会将功能添加到composer require命令中，在大多数情况下不需要额外的选项或命令来运行。

如果目标Magento包的composer require命令失败，可能需要以下之一。

以其他Magento产品开始的安装

如果本地Magento安装之前已经从没有安装插件的旧版本或版本更新，根composer.json文件可能仍然包含需要更新到当前Magento要求的早期包的值，在更新到目标Magento产品之前。

在这种情况下，在继续运行目标Magento产品的预期的composer require命令之前，运行以下命令以纠正现有的composer.json文件，并使用适当的值。

composer require <current_Magento_package> <current_version> --base-magento-edition '<Open Source|Commerce>' --base-magento-version <original_Magento_version>

这些选项对Magento Cloud安装无效。

冲突的自定义值

如果composer.json文件包含与插件根据安装的Magento元包期望的值不匹配的自定义更改，则可能需要将这些条目更正为与目标Magento版本兼容的值。

要交互式地解决这些冲突，重新运行带有--interactive-magento-conflicts选项的composer require命令。

要使用预期的Magento值覆盖所有冲突的自定义值，重新运行带有--use-default-magento-values选项的composer require命令。

绕过插件

要使用插件更新运行本地的composer require命令，使用--skip-magento-root-plugin选项。

刷新Web安装向导的插件

如果Magento根目录中的var目录已被清除，则可能需要重新在该目录中安装插件，以便通过Web安装向导更新Magento时能够运行。

要在var中重新安装插件，请在Magento根目录中运行以下命令。

composer magento-update-plugin install

示例用例：从Magento 2.2.8升级到Magento 2.3.1

没有magento/composer-root-update-plugin

在 Magento Open Source 2.2.8 安装的项目目录中，用户尝试运行 composer require 和 composer update 命令以安装 Magento Open Source 2.3.1，结果如下：

$ composer require magento/product-community-edition 2.3.1 --no-update
./composer.json has been updated
$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for magento/product-community-edition 2.3.1 -> satisfiable by magento/product-community-edition[2.3.1].
    - magento/product-community-edition 2.3.1 requires magento/magento2-base 2.3.1 -> satisfiable by magento/magento2-base[2.3.1].
  ...
    - sebastian/phpcpd 2.0.4 requires symfony/console ~2.7|^3.0
  ...
    - magento/magento2-base 2.3.1 requires symfony/console ~4.1.0 -> satisfiable by symfony/console[v4.1.0, v4.1.1, v4.1.10, v4.1.11, v4.1.2, v4.1.3, v4.1.4, v4.1.5, v4.1.6, v4.1.7, v4.1.8, v4.1.9].
    - Conclusion: don't install symfony/console v4.1.11|install symfony/console v2.8.38
    - Installation request for sebastian/phpcpd 2.0.4 -> satisfiable by sebastian/phpcpd[2.0.4].

此错误发生是因为 magento/project-community-edition 2.2.8 的 composer.json 文件中的 "require-dev" 部分与 magento/product-community-edition 2.3.1 新版本的依赖项冲突。2.2.8 的 composer.json 文件有一个 "require-dev" 条目 sebastian/phpcpd: 2.0.4，它依赖于 symfony/console: ~2.7|^3.0，但是 magento/product-community-edition 2.3.1 所需要的 magento/magento2-base 包依赖于 symfony/console: ~4.1.0，这与 ~2.7|^3.0 约束允许的版本不兼容。

由于 sebastian/phpcpd 依赖项存在于根 composer.json 文件中，而不是 magento/product-community-edition 2.2.8 的子依赖项之一，因此当 magento/product-community-edition 版本更改时，Composer 不会更新它。

在 magento/project-community-edition 2.3.1 的 composer.json 文件中，那个 sebastian/phpcpd 在 "require-dev" 中的条目已更改为 ~3.0.0，这与 magento/magento2-base 2.3.1 允许的 symfony/console 版本兼容。然而，如果没有这个插件，Composer 就不知道值需要更改，因为升级 Magento 的命令使用的是 magento/product-community-edition 元包，而不是根 magento/project-community-edition 项目包。

这只是在 Magento 2.2.8 和 2.3.1 之间更改根项目 composer.json 文件的一个例子。还有其他几个更改，未来的 Magento 版本可能（并且很可能会）需要进一步更新该文件。

用户可以手动更改根项目 composer.json 文件，无需插件，但需要更改的值可能因所涉及的 Magento 版本而异，并且用户自定义的值可能已覆盖了 Magento 默认值。这意味着对于每个用户，必要的升级步骤可能都不同，并且为给定的用户配置手动确定正确的更改可能存在错误。

为了参考，以下是 Magento Open Source 版本 2.2.8 和 2.3.1 的默认安装（没有用户自定义）的 "require" 和 "require-dev" 部分。需要注意的是，这些 composer.json 的部分不是唯一可能更改的。例如，"autoload" 和 "conflict" 部分，它们也可能影响 Magento 功能，并需要与安装的 Magento 版本保持更新。

• 2.2.8

   "require": {
       "magento/product-community-edition": "2.2.8",
       "composer/composer": "@alpha"
   },
   "require-dev": {
       "magento/magento2-functional-testing-framework": "2.3.13",
       "phpunit/phpunit": "~6.2.0",
       "squizlabs/php_codesniffer": "3.2.2",
       "phpmd/phpmd": "@stable",
       "pdepend/pdepend": "2.5.2",
       "friendsofphp/php-cs-fixer": "~2.2.1",
       "lusitanian/oauth": "~0.8.10",
       "sebastian/phpcpd": "2.0.4"
   }
  

• 2.3.1

   "require": {
       "magento/product-community-edition": "2.3.1"
   },
   "require-dev": {
       "friendsofphp/php-cs-fixer": "~2.13.0",
       "lusitanian/oauth": "~0.8.10",
       "magento/magento2-functional-testing-framework": "~2.3.13",
       "pdepend/pdepend": "2.5.2",
       "phpmd/phpmd": "@stable",
       "phpunit/phpunit": "~6.5.0",
       "sebastian/phpcpd": "~3.0.0",
       "squizlabs/php_codesniffer": "3.3.1",
       "allure-framework/allure-phpunit": "~1.2.0"
   }
  

使用 magento/composer-root-update-plugin

在 Magento Open Source 2.2.8 安装的项目目录中，用户在升级到 Magento Open Source 2.3.1 之前，运行 composer require magento/composer-root-update-plugin ~1.1 --no-update 和 composer update 命令。

$ composer require magento/composer-root-update-plugin ~1.1 --no-update
./composer.json has been updated
$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing magento/composer-root-update-plugin (1.1.0): Downloading (100%)         
Installing "magento/composer-root-update-plugin: 1.1.0" for the Web Setup Wizard
Loading composer repositories with package information
Updating dependencies
Package operations: 18 installs, 0 updates, 0 removals
  - Installing ...
  ...
  - Installing magento/composer-root-update-plugin (1.1.0): Downloading (100%)
Writing lock file
Generating autoload files
Writing lock file
Generating autoload files

与正常的 composer require 一样，magento/composer-root-update-plugin 被添加到 composer.json 文件中。该插件还会在依赖项验证期间由 Magento Web Setup Wizard 使用的目录中安装自己。

安装插件后，用户继续执行 composer require 命令以安装 Magento Open Source 2.3.1（这里使用 --verbose 模式进行演示）。

$ composer require magento/product-community-edition 2.3.1 --no-update --verbose
 [Magento Open Source 2.3.1] Base Magento project package version: magento/project-community-edition 2.2.8
 [Magento Open Source 2.3.1] Removing require entries: composer/composer
 [Magento Open Source 2.3.1] Adding require-dev constraints: allure-framework/allure-phpunit=~1.2.0
 [Magento Open Source 2.3.1] Updating require-dev constraints: magento/magento2-functional-testing-framework=~2.3.13, phpunit/phpunit=~6.5.0, squizlabs/php_codesniffer=3.3.1, friendsofphp/php-cs-fixer=~2.13.0, sebastian/phpcpd=~3.0.0
 [Magento Open Source 2.3.1] Adding conflict constraints: gene/bluefoot=*
 [Magento Open Source 2.3.1] Updating autoload.psr-4.Zend\Mvc\Controller\ entry: "setup/src/Zend/Mvc/Controller/"
Updating composer.json for Magento Open Source 2.3.1 ...
 [Magento Open Source 2.3.1] Writing changes to the root composer.json...
 [Magento Open Source 2.3.1] <path>/composer.json has been updated
./composer.json has been updated

插件检测到用户请求 magento/product-community-edition 的 2.3.1 版本，并查找相应的 magento/project-community-edition 2.3.1 根项目包的 composer.json 文件。它找到 2.2.8 和 2.3.1 之间的不同值，并相应地更新本地 composer.json 文件，然后让 Composer 继续执行正常的 composer require 功能。

更新了 Magento Open Source 2.3.1 的根 composer.json 文件后，用户继续执行 composer update 命令。

$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 118 installs, 246 updates, 5 removals
  - Removing symfony/polyfill-php55 (v1.11.0)
  ...
Writing lock file
Generating autoload files

有了来自 Magento Open Source 2.3.1 的更新值，symfony/console 冲突不再存在，并且更新按预期进行。

以下是在使用插件在 Magento Open Source 2.2.8 安装上运行 composer require magento/product-community-edition 2.3.1 --no-update 命令后，从 composer.json 文件中获取的 "require" 和 "require-dev" 部分。它们包含与默认 Magento Open Source 2.3.1 根 composer.json 文件（增加 magento/composer-root-update-plugin 的需求）完全相同的条目。

 "require": {
     "magento/product-community-edition": "2.3.1",
     "magento/composer-root-update-plugin": "~1.1"
 },
 "require-dev": {
     "allure-framework/allure-phpunit": "~1.2.0",
     "magento/magento2-functional-testing-framework": "~2.3.13",
     "phpunit/phpunit": "~6.5.0",
     "squizlabs/php_codesniffer": "3.3.1",
     "phpmd/phpmd": "@stable",
     "pdepend/pdepend": "2.5.2",
     "friendsofphp/php-cs-fixer": "~2.13.0",
     "lusitanian/oauth": "~0.8.10",
     "sebastian/phpcpd": "~3.0.0"
 }

许可证

本分发中包含的每个 Magento 源文件均根据 OSL 3.0 许可。

开源软件许可（OSL 3.0）.

有关 OSL 3.0 许可证的完整文本，请参阅 LICENSE.txt，或联系 license@magentocommerce.com 获取副本。