README

通过创建内容迁移，轻松地在CraftCMS网站安装之间迁移内容。您可以选择要迁移的元素（条目、分类、用户、全局变量）并创建一个原生Craft内容迁移文件，该文件可以提交到您的版本控制系统。然后，可以在不同的CraftCMS安装上应用迁移（们），以即时创建和更新内容，而无需多次输入数据。通过使用迁移，您可以确保您的各种网站环境（本地、预发布、生产等）保持同步并更新。

安装

插件商店（简单方法）

在Craft控制面板中，转到设置 -> 插件
搜索“迁移助手”
点击“安装”按钮

Composer命令行（手动方法）

转到命令行并 cd 到您的项目根目录
通过composer下载插件 composer require dgrigg/craft-migration-assistant
在Craft控制面板中，转到设置 -> 插件
点击“安装”按钮以安装迁移助手

概述

迁移助手可以为以下元素创建内容迁移

条目
分类
全局变量
用户

要创建迁移，请选择要迁移的元素，然后点击页面底部的齿轮和“创建迁移”按钮。对于全局值，请使用全局屏幕上的“创建迁移”按钮。

内容迁移依赖于一个工作流程，其中首先迁移相关/依赖元素。例如，如果您有一个具有一些选中分类的条目，则在条目迁移正确工作之前，分类需要存在于目标网站上。这意味着首先创建分类的迁移。这对于用户、资产以及其他相关条目/元素也是如此。在资产的情况下，您需要确保匹配的资产（基于资产源/文件夹/文件名）存在于目标网站上。

迁移文件将在 craft/migrations 文件夹中创建。迁移文件名将包含迁移元素的别名/处理程序。将新的迁移文件移动到您的目标环境，最好使用版本控制。

在您的开发环境中

git add .
git commit -am 'new migration'
git push

在您的目标环境中

git pull

当在您的目标环境中发现新的迁移（们）时，会出现徽章以通知您。点击“迁移助手”标签并运行新迁移。您可以通过单击“运行迁移”按钮简单地运行所有挂起的迁移，或者选择要运行的个别迁移。您还可以从原生的Craft/工具/迁移标签中运行迁移（这仅允许您运行所有挂起的迁移，而不能运行个别迁移）。

迁移助手使用Craft内置的迁移器来运行迁移。失败的迁移将被回滚，数据库将返回到迁移前的状态。您可以通过Craft日志和迁移日志查看迁移失败的原因的详细信息。在许多情况下，这只是迁移有依赖项（例如，必需的字段）尚未在目标网站上设置或缺少字段/插件的情况。

您还可以通过点击迁移助手/Migrations 页面上的“应用”标签来查看以前应用的迁移。这将显示已经应用和本地创建的迁移（无需在本地运行）。请注意，如果您创建了空白迁移（通过点击创建迁移按钮而不选择元素），它们将显示在新迁移列表中，这样您就有机会使用自定义迁移代码在本地测试和运行它们。

待定迁移

您可以通过多种方式运行迁移。Craft的两种标准方法是：通过命令行./craft migrate/all或通过Craft CP实用工具迁移标签。这两种方法都会运行所有可用的内容迁移。可能存在您只想运行单个内容迁移的情况。为此，请使用CP中的“迁移助手/Migrations”面板。您可以选择运行一个、多个或所有可用的迁移。如果需要，您还可以重新运行以前应用的迁移。

字段支持

迁移助手目前支持所有CraftCMS核心字段类型

地址
资产
类别
复选框
颜色
国家
日期
下拉菜单
电子邮件
条目
图标
轻触开关
矩阵
货币
多选
数字
纯文本
单选按钮
表格
标签
时间
网址
用户

此外，它还支持

额外字段支持

为了支持额外的字段类型和特殊内容，您可以使用事件处理器来自定义导入/导出功能。要处理自定义字段类型的导入/导出，您的插件/模块应该监听从BaseContentMigration类触发的导出/导入事件。有关如何使用导出和导入事件的示例，请参阅extensions/LinkFieldExtension.php。

以下列表显示了迁移助手具有事件处理的元素类型，允许您修改导出/导入数据以支持自定义字段。

条目
类别
全局设置
用户

使用事件

在导出事件期间，您可以修改$event->value数据以包含不在要导出的数据中的任何附加设置。这也是更新对链接元素的引用的正确位置，将元素id更改为在环境中可移植的handle/slugs。

@event ExportEvent - Triggered before an element is exported
const EVENT_BEFORE_EXPORT_ELEMENT = 'beforeExport';

@event ExportEvent - Triggered before an element field value is exported
const EVENT_BEFORE_EXPORT_FIELD_VALUE = 'beforeExportFieldValue';

@event ImportEvent - Triggered before an element is imported, can be cancelled
const EVENT_BEFORE_IMPORT_ELEMENT = 'beforeImport';

@event ImportEvent - Triggered before an element field value is imported
const EVENT_BEFORE_IMPORT_FIELD_VALUE = 'beforeImportFieldValue';

@event ImportEvent - Triggered before an element is imported
const EVENT_AFTER_IMPORT_ELEMENT = 'afterImport';

//Custom field example
Event::on(Fields::class, Fields::EVENT_BEFORE_EXPORT_ELEMENT, function(ExportEvent $event) {
    $value = $event->value;
    $value['settings']['special_setting'] = 'some special setting value';
    $event->value = $value;
});

在导入期间，您可以在导入之前修改数据或处理导入后的元素，无论是创建还是更新。

在导入之前，$event->element是基于handle匹配的元素模型（将要导入的、更新的或创建的）。$event->value属性是用于填充元素模型的原始数据。您可以根据需要更改$event->element和$event->value中的属性以影响导入数据。有关示例，请参阅extensions/LinkFieldExtension.php。

//Custom fields
Event::on(Fields::class, Fields::EVENT_BEFORE_IMPORT_ELEMENT, function(ExportEvent $event) {
   $element = $event->element;
   $element->special_value = $event->value['special_setting'];
   $event->element = $element;
});

在导入后，您可以访问$event->element和$event->value以执行与元素相关的其他操作（如果需要）。

Event::on(Fields::class, Fields::EVENT_AFTER_IMPORT_ELEMENT, function(ExportEvent $event) {
   $event->value['special_value'] = 'some special value';
});

如果需要，您还可以取消导入并提供错误消息。错误消息将写入Craft网络日志。

//Custom fields
Event::on(Fields::class, Fields::EVENT_BEFORE_IMPORT_ELEMENT, function(ExportEvent $event) {
    $event->isValid = false;
    $event->error = 'my reason for cancelling the imort';
});

字段数据中包含id的值应转换为handle/slug或其他字符串值，以便在目标网站上查找，而无需依赖于匹配的id值，因为id值可能在网站数据库实例之间有所不同。请参阅ElementHelper:getSourceHandle和ElementHelper:populateIds以获取更多信息。

对于导入自定义字段，导入的值应与所需的输入结构匹配。请检查字段类型的文档和代码，以获取确定正确结构的帮助。

用户

关于用户迁移的特殊说明。迁移中只导出用户的内容。这包括用户名、电子邮件、任何自定义字段布局值（包括地址）和权限。密码、用户激活、用户登录信息不会迁移。

权限

默认情况下，所有具有管理员权限的用户都可以完全访问迁移助手并创建内容迁移。非管理员用户可以在Craft的用户/权限部分授予访问迁移助手和创建内容迁移的权限。

自定义迁移

除了生成的迁移外，您还可以使用MigrationManger创建空迁移，用于删除字段和创建内容等任务。要创建空迁移，只需在迁移助手/创建迁移选项卡上单击“创建迁移”。一个新的空迁移将被添加到craft/migrations文件夹。

查看示例。

要了解有关创建自定义迁移的更多信息

从迁移助手3升级

迁移助手不再包括对字段、部分、设置等迁移的支持。Craft的核心项目配置设置是同步Craft结构/设置跨环境的一种更好的机制。请注意，由于Craft核心元素和服务的变化，迁移需要在同一Craft主要版本中生成和执行。

鸣谢

由Agne Alesiute设计的Flying Duck图标来自Noun Project

дгригг / 工艺迁移助手

维护者

详细信息