README

银色沙滩CMS升级器已经基本完成了它的任务。银色沙滩CMS核心团队在近期内不会积极地对其进行更多的工作。如果社区成员想成为维护者，那么我们很高兴在做一些基本的尽职调查后授予他们合并权限。如果您想维护此存储库，请提出一个问题。

升级器

升级器是一个框架，用于自动化处理依赖库中API更改的代码升级。有关逐步说明，请参阅4.x 升级指南。

由 @sminnee 和 @tractorcow 开发，得到 @camspiers 的灵感和鼓励。

安装

升级器可以作为phar可执行文件使用。

要安装PHAR可执行文件

下载升级器作为PHAR可执行文件或 wget https://silverstripe.github.io/silverstripe-upgrader/upgrade-code.phar
使文件可执行 chmod +x upgrade-code.phar
将文件移动到您的路径中的文件夹，例如 sudo mv upgrade-code.phar /usr/local/bin/upgrade-code

使用composer全局安装升级器

您可以使用composer全局安装升级器。这可以更容易地更新到新版本，但是如果您已经全局安装了其他包，则可能会出现依赖冲突。

要全局安装，请运行

composer global require silverstripe/upgrader

确保您的 $HOME/.composer/vendor/bin 目录在您的PATH中（或您的OS的等效目录，例如Windows上的 C:\Users\\AppData\Roaming\Composer\vendor\bin）。

echo 'export PATH=$PATH:~/.composer/vendor/bin/' >> ~/.bash_profile

然后您可以在项目根目录中运行此脚本，使用 upgrade-code <command>。如果不是在根目录中运行，请使用 --root-dir=/path。

可用命令

概述

以下命令可用

all: 聚合升级SilverStripe项目的所有必需命令。
add-namespace: 向文件添加命名空间。
recompose: 升级composer文件以使用最新的SilverStripe版本。
doctor: 运行为本项目配置的所有清理任务。
environment: 将设置从 _ss_environment.php 迁移到 .env。
inspect: 运行额外的升级后检查、警告和重写，以整理松散的末端。
reorganise: 将项目文件夹从SS3的 mysite 惯例重新组织到SS4的 app 惯例。
self-update: 获取最新的SilverStripe升级器版本。
upgrade: 将一组代码文件升级以与库的新版本一起使用。
webroot: 将SilverStripe项目更新为使用 public 网站根目录。

`all`

以推荐的顺序并以合理的默认值运行所有命令。

upgrade-code all \
    [--root-dir=<root>] \
    [--composer-path=composer] \
    [--strict] \
    [--recipe-core-constraint=RECIPE-CORE-CONSTRAINT] \ 
    [--namespace] \
    [--skip-reorganise] \
    [--skip-webroot] \
    [--skip-add-namespace] \
    [--psr4]

示例

upgrade-code all

除非您的网站非常简单，否则在第一次运行此命令时很可能不会成功。它被设计为连续运行，以帮助您找到错误并进行调试。如果命令运行成功，您将在最后获得所有警告的摘要。
所有更改都已写入。这是必要的，因为后续某些命令期望之前已经执行了特定的步骤。
它相当于按照以下顺序运行以下步骤
- recompose
- 环境
- 添加命名空间
- 升级
- 检查
- 重组
- 网站根目录
使用 --skip 标志可以跳过可选步骤。
--namespace 和 --psr4 被转发到 添加命名空间 命令。
--strict、cwp-constraint 和 --recipe-core-constraint 被转发到 recompose 命令。

`添加命名空间`

您可以使用以下命令将命名空间添加到任何类中

upgrade-code add-namespace <namespace> <filepath> [--root-dir=<dir>] [--write] [--recursive] [--psr4] [-vvv] [--autoload] [--autoload-dev]

示例

upgrade-code add-namespace "My\Namespace" ./mysite/code/SomeCode.php --write -vvv

请确保在项目根目录中运行此命令，或使用 --root-dir 设置根目录。
请注意，在命名空间中引用斜杠时，要么加引号，要么转义。
如果您只想进行Dry-run，请跳过 --write 参数。
如果您有多个命名空间级别，可以使用 --recursive 或 -r 参数来更新这些级别。
如果您的文件路径遵循PSR-4，您可以在递归参数中添加 --psr4 或 -p 参数来自动完成子目录中的命名空间。可以使用 --autoload 和 --autoload-dev 参数在 composer.json 文件中快速配置自动加载。

这将命名空间 SomeCode.php 类文件，并将映射添加到项目中 ./.upgrader.yml 文件中。

一旦添加了命名空间，您将需要运行下面的 升级 任务来迁移引用了这些未命名空间版本类代码。

`recompose`

您可以使用此命令将 composer.json 依赖项从 SilverStripe 3 升级到 Silverstripe 4。

upgrade-code recompose [--root-dir=<dir>] [--write] [--strict] [-vvv] [--recipe-core-constraint=*] [--cwp-constraint] [--composer-path=composer]

示例

upgrade-code recompose --root-dir=/var/www/SS_project --write --recipe-core-constraint="4.1"

运行此命令后，您可能会遇到损坏的依赖项。您必须手动解决这些问题。
您可以通过 --recipe-core-constraint 选项指定要升级到的 SilverStripe 版本。如果为空，您将升级到最新稳定版本。
如果您正在升级 CWP 项目，请使用 --cwp-constraint 而不是 --recipe-core-constraint。 --cwp-constraint 允许您针对 cwp/cwp-core 的特定版本进行目标定位。
此脚本依赖于 composer 来获取最新的依赖项。如果 composer 在您的路径中，并且被命名为 composer 或 composer.phar，则无需执行任何操作。否则，您必须指定 --composer-path 选项。
如果您指定了 --strict 选项，则对依赖项的约束将更加严格。
如果您只想进行Dry-run，请跳过 --write 参数。您将在最后有机会保存更改。

`doctor`

在迁移到早期版本时，某些项目资源（例如 .htaccess / index.php）可能已过时，并使站点处于无法卸载的状态。

您可以在项目中运行以下命令来运行一系列旨在自动解决这些问题的任务

upgrade-code doctor [--root-dir=<root>]

可以在 .upgrade.yml 中指定任务，其语法如下

doctorTasks:
  SilverStripe\Dev\CleanupInstall: src/Dev/CleanupInstall.php

给定的任务必须有一个 __invoke() 方法。这将被传递以下参数

InputInterface $input
OutputInterface $output
string $basePath 项目根路径

注意：建议仅在您的网站不是响应式的情况下运行此命令，因为这些可能会覆盖对 .htaccess 或其他项目文件的用户自定义修改。

`环境`

您可以使用此命令将 SilverStripe 3 的 _ss_environment.php 文件迁移到 SilverStripe 4 使用的 .env 格式。

upgrade-code environment [--root-dir=<dir>] [--write] [-vvv]

示例

upgrade-code environment --root-dir=/var/www/SS_project --write -vvv

此命令不会假设您的 _ss_environment.php 文件位于根目录中。像 SilverStripe 3 一样，它将递归地检查父文件夹，直到找到 _ss_environment.php 或不可读的文件夹。
如果您的 _ss_environment.php 文件包含异常逻辑（条件语句或循环），您将收到警告。 upgrade-code 仍然会尝试转换文件，但您应该仔细检查输出。
如果您只想进行测试运行，请跳过 --write 参数。

`检查`

一旦一个项目的所有类名都已迁移，并且达到“可加载”状态（即，所有类都引用或扩展了真实类），则可以运行 inspect 命令来执行额外的自动代码重写。

此步骤还将警告任何可能阻止成功升级的代码问题。

注意：此步骤与 upgrade 是分开的，因为在此步骤中，您的项目代码被加载到真实内存中，以获取完整的项目上下文。为了准备此步骤，您的网站应更新到基本阶段，包括所有模块升级和命名空间更改。

您可以使用以下命令（并刷新必要的 composer 自动加载文件）来运行此命令

composer dump-autoload
upgrade-code inspect <path> [--root-dir=<root>] [--write] [-vvv] [--skip-visibility]

这将加载所有类到内存中，并推断每个文件中使用的所有对象的类型。它将使用这些推断的类型来自动更新方法使用。

可见性更新

如果可能，命令将属性和函数更新为其父类的正确可见性。

添加 --skip-visibility 选项来忽略此操作。

`重组`

您可以使用此命令重新组织您的文件夹结构，以符合 SilverStripe 4.1 中引入的新结构。您的 mysite 文件夹将被重命名为 app，您的 code 文件夹将被重命名为 src。

upgrade-code reorganise [--root-dir=<dir>] [--write] [--recursive] [-vvv]

示例

upgrade-code reorganise --root-dir=/var/www/SS_project --write -vvv

如果您只想进行测试运行，请跳过 --write 参数。
该命令将尝试查找代码库中任何 mysite 的出现，并将其显示为警告。

`self-update`

此命令将升级程序工具本身到最新版本。它不接受任何参数。由于该工具处于积极开发中，并且持续改进，因此保持工具更新非常重要。

upgrade-code self-update

`升级`

完成代码命名空间化后，您可以运行以下代码来重命名所有引用。

upgrade-code upgrade <path> [--root-dir=<root>] [--write] [--rule] [-vvv] [---prompt]

示例

upgrade-code upgrade ./mysite/code

这将查看所有类映射，并将任何对重命名类的引用重命名为正确的值。

此外，所有 .yml 配置文件都将重写字符串。如果要仅升级 PHP 文件，可以使用 --rule=code。如果您已经升级了代码，则可以使用 --rule=config 仅针对配置文件进行目标。

排除升级中的字符串

当升级包含字符串的代码时，升级器需要做出假设，即字符串是否指代类名，并确定它是否是替换的候选。

如果您有一个包含不表示类名字符串的代码块，并且应该从重写中排除（即使它们与正在重写的类名匹配），则可以添加一个带有 @skipUpgrade 标签的 docblock，升级器将不会更改此代码中的任何部分。

示例

/** @skipUpgrade */
return Injector::inst()->get('MyService');

在上面的示例中，即使 MyService 可能会被重命名，也不会对其进行修改。

此 docblock 可以应用于字符串语句之前，或代码块之前（例如方法、循环或条件）。

注意，@skipUpgrade 不会阻止升级类文字，并且仅影响字符串，因为这些不是模糊的，升级器可以安全地更新这些引用。

将数据库引用升级到现在具有命名空间的 DataObject 子类

如果任何 DataObject 子类已被命名空间化，我们将在配置文件（例如 legacy.yml）中指定它们。这告诉 SilverStripe 在运行 dev/build 时重映射这些类名。

---
Name: mymodulelegacy
---
SilverStripe\ORM\DatabaseAdmin:
  classname_value_remapping:
    MyModelClass: 'Me\MyProject\Model\MyModelClass'

升级本地化

您还可以升级以下文件中的所有本地化字符串

lang/*.yml 中的键
所有 *.php 文件中的 _t() 方法键
所有 *.ss 文件中的 <%t 和 <% _t() 方法键

您可以使用以下命令在这些密钥上运行升级器

upgrade-code upgrade <path> --rule=lang

由于此升级通常仅在提供自身字符串的项目上执行，因此当运行常规升级时，默认情况下不会包含此规则。

类重命名

类映射可用于将字符串字面量引用转换为命名空间类。有时不清楚一个字符串字面量是否指向映射的类。这就是renameWarnings发挥作用的地方。

一个模糊重命名的例子

private static $has_one = [
    'Image' => 'Image',
];

您可以使用yaml指定应视为模糊的重命名的类

renameWarnings:
  - File
  - Image

上述配置将在将File和Image实例重命名为它们相应的类映射时显示警告。

添加--prompt选项以手动批准模糊的类重命名。

.upgrade.yml规范

.upgrade.yml文件将遵循以下规范

# Upgrade these classes
mappings:
  OldClass: My\New\Class
  SS_MyClass: NewClass
# File extensions to look at
fileExtensions:
  - php
# Don't rewrite these `private static config` settings
skipConfigs:
  - db
  - db_for_versions_table
# Don't rewrite these keys in YML
skipYML:
  - MySQLDatabase
  - Filesystem
# Namespaces to add (note: It's recommended to specify these on the CLI instead of via config file)
add-namespace:
  namespace: The\Namespace
  path: src/
# List of tasks to run when running `upgrade-code doctor`
doctorTasks:
  SilverStripe\Dev\CleanupInstall: src/Dev/CleanupInstall.php
warnings:
  classes:
    MyClass:
      message: 'MyClass has been removed'
      url: 'http://my-domain/upgrade-instructions'
  methods:
    'MyClass->myInstanceMethod()':
      message: 'Use otherMethod() instead'
      replacement: 'otherMethod'
    'MyClass::myStaticMethod()':
      message: 'Use otherMethod instead'
      replacement: 'otherMethod'
    'obsoleteMethod()':
      message: 'obsoleteMethod is removed'
  props:
    'MyClass->myInstanceProp'
      message: 'Use otherProp instead'
      replacement: 'otherProp'
    'MyClass::myStaticProp'
      message: 'Use otherProp instead'
      replacement: 'otherProp'
    'obsoleteProp':
      method: 'obsoleteProp is removed'
  functions:
    'myFunction()':
      message: 'Use otherFunction() instead'
      replacement: 'otherFunction'
  constants:
    'MY_CONSTANT':
      message: 'Use OTHER_CONSTANT instead'
      replacement: 'OTHER_CONSTANT'
    'MyClass::MY_CONSTANT':
      message: 'Use OTHER_CONSTANT instead'
      replacement: 'OTHER_CONSTANT'
excludedPaths:
  - '*thirdparty*'

`网站根目录`

配置您的项目以使用SilverStripe 4.1引入的public网络根结构（详细信息。

upgrade-code webroot [--root-dir=<root>] [--write] [--composer-path=composer] [-vvv]

示例

upgrade-code webroot /var/www/ss_project

您的项目必须使用silverstripe/recipe-core 4.1或更高版本才能使用此命令。否则您将收到警告。
如果您已自定义服务器配置文件（.htaccess和/或web.config），您必须手动将其与silverstripe/recipe-core提供的通用配置进行协调。
运行此命令后，您需要更新您的虚拟主机配置，以便指向新创建的public文件夹，并且需要重写任何硬编码的路径。

silverstripe / upgrader

维护者

详细信息