README

UXDM帮助开发者将数据从一个系统或格式迁移到另一个系统或格式。

安装

UXDM可以使用Composer轻松安装。只需从项目的根目录运行以下命令。

composer require divineomega/uxdm

如果您之前从未使用过Composer依赖管理器，请访问Composer网站以获取有关如何开始的更多信息。

快速入门

1. 创建一个新PHP文件来包含您的UXDM迁移代码。在这个例子中，我们将其命名为user-csv-import.php。如果需要，请记住添加require 'vendor/autoload.php'和相关的use语句。

2. 创建源和目标对象。此示例使用CSV源和PDO（数据库）目标。

$csvSource = new CSVSource('users.csv');

$pdoDestination = new PDODestination(new PDO('mysql:dbname=test-database;host=127.0.0.1', 'root', 'password'), 'users');

1. 创建和配置一个新的UXDM迁移对象。

$migrator = new Migrator;
$migrator->setSource($csvSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->withProgressBar()
         ->migrate();

1. 运行您刚刚创建的迁移。在这个例子中，我们可以仅从命令行运行php user-csv-import.php并会得到一个进度条。

请参阅下面的部分，以获取有关可用源和目标对象的更多信息，以及更高级的使用示例。

迁移

每个UXDM迁移都需要一个源对象和至少一个目标对象。这些确定数据读取和写入的位置和方式。UXDM包与各种源和目标对象一起工作，包括以下内容。

• PDO（PHP数据库对象）源 & 目标
• Eloquent（如Laravel中使用）源 & 目标
• Doctrine（如Symfony中使用）目标
• CSV（逗号分隔值）源 & 目标
• Excel源 & 目标
• 关联数组源 & 目标
• JSON文件源 & 目标
• XML源 & 目标
• WordPress帖子源
• WordPress用户源
• 调试输出目标

其中一些是UXDM核心包内建的，而其他则是作为单独的包提供的。

可以以任何组合使用源和目标对象。数据可以从CSV迁移到数据库，就像从数据库迁移到CSV一样容易。

您还可以在同一个迁移中使用类似的源和目标对象。例如，UXDM的常见用法是使用PDO源和PDO目标将数据从一个数据库传输到另一个数据库。

请参阅源 & 目标页面，了解更多源和目标以及它们的使用详细文档。

示例

数据库到数据库迁移

以下是一个基本的数据库到数据库UXDM迁移示例。

$pdoSource = new PDOSource(new PDO('mysql:dbname=old-test;host=127.0.0.1', 'root', 'password123'), 'users');

$pdoDestination = new PDODestination(new PDO('mysql:dbname=new-test;host=127.0.0.1', 'root', 'password456'), 'new_users');

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->withProgressBar()
         ->migrate();

此迁移将把id、email和name字段从old-test数据库中的users表移动到new-test数据库中的new_users表，用相同的id（键字段）替换任何现有的记录。

源数据验证

您可以使用UXDM验证源数据。如果在迁移过程中验证失败，迁移将停止，并抛出ValidationException。但是，如果调用了->validateBeforeMigrating()，则所有数据行将在迁移开始之前预先验证。

下面的代码显示了如何验证不同的字段。

$pdoSource = new PDOSource(new PDO('mysql:dbname=old-test;host=127.0.0.1', 'root', 'password123'), 'users');

$pdoDestination = new PDODestination(new PDO('mysql:dbname=new-test;host=127.0.0.1', 'root', 'password456'), 'new_users');

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setValidationRules([
            'id' => [new Required(), new IsNumeric()],
            'email' => [new Required(), new IsString(), new IsEmail()],
            'name' => [new Required(), new IsString()],
         ])
      // ->validateBeforeMigrating()
         ->setKeyFields(['id'])
         ->withProgressBar()
         ->migrate();

此迁移将验证源数据是否符合定义的验证规则。

• 'id'必须存在，并且是数字。
• 'email' 字段必须存在，并且是一个字符串，格式正确的电子邮件地址。
• 'name' 字段必须存在，并且是一个字符串。

UXDM 使用了 Omega Validator 包。请参阅其文档了解所有可用的验证规则。

从源到目标映射字段名称

以下示例说明了UXDM如何将字段名称从源映射到目标。

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->setFieldMap(['name' => 'full_name'])
         ->withProgressBar()
         ->migrate();

此迁移将数据从源 name 字段移动到目标 full_name 字段，同时仍然正常移动 id 和 email 字段。

在迁移过程中转换数据行

有时您希望从源移动到目标的数据需要进行转换。这可能包括更改现有数据项、添加新数据项或删除不需要的项目。

UXDM 允许您创建一个或多个转换器对象，并将它们添加到迁移中。请参阅以下示例了解如何使用转换器来操作您的数据。

更改现有数据项

此示例说明如何在迁移过程中转换现有数据项。

class NameCaseTransformer implements TransformerInterface
{
    public function transform(DataRow $dataRow): void
    {
        $nameDataItem = $dataRow->getDataItemByFieldName('name');
        $nameDataItem->value = ucwords(strtolower($nameDataItem->value));
    }
}

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->addTransformer(new NameCaseTransformer())
         ->withProgressBar()
         ->migrate();

此迁移将确保所有名称字段具有一致的大小写。

添加数据项

此示例说明如何在迁移过程中添加新数据项。

class AddRandomNumberTransformer implements TransformerInterface
{
    public function transform(DataRow &$dataRow): void
    {
        $dataRow->addDataItem(new DataItem('random_number', rand(1,1000)));
    }
}

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->addTransformer(new AddRandomNumberTransformer())
         ->withProgressBar()
         ->migrate();

此迁移将为每行数据添加一个名为 random_number 的随机数。然后，它将与其他字段一起迁移到目标数据库。

删除数据项

此示例演示了如何从数据行中删除数据项。如果您想使用其值但不实际将其迁移到目标，您可能希望这样做。

class EmailToHashTransformer implements TransformerInterface
{
    public function transform(DataRow $dataRow): void
    {
        $emailDataItem = $dataRow->getDataItemByFieldName('email');
        $dataRow->addDataItem(new DataItem('email_hash', md5($emailDataItem->value)));
        $dataRow->removeDataItem($emailDataItem);
    }
}

$migrator = new Migrator;
$migrator->setSource($pdoSource)
         ->setDestination($pdoDestination)
         ->setFieldsToMigrate(['id', 'email', 'name'])
         ->setKeyFields(['id'])
         ->addTransformer(new EmailToHashTransformer())
         ->withProgressBar()
         ->migrate();

此迁移从源 email 字段获取数据，创建一个新的包含电子邮件地址 md5 的 email_hash 数据项，然后删除原始的 email 数据项。这个新的 email_hash 将与其他字段一起迁移到目标数据库，不包括已删除的 email 字段。