README

以多种形式从SilverStripe导入和导出数据，包括CSV。此模块是框架中找到的BulkLoader功能的替代品/重写。

此模块是原始模块的分支

加载过程

从源（BulkLoaderSource）检索原始数据。
数据以可迭代的行（每行是标题->值的映射数组）提供。
行根据用户/开发者提供的映射映射到标准格式。
将数据设置/链接/转换为占位符DataObject。
现有记录替换占位符，或占位符成为全新的DataObject。
验证并保存DataObject。
所有结果存储在BulkLoader_Result中。

用户定义的列映射

用户可以选择哪些列映射到DataObject字段。这消除了定义标题或根据给定模式定义标题的需要。用户可以声明数据的第一行实际上是标题行。映射将在下次在同一GridField上执行导入时保存。

网格字段导入器

这是一个网格字段组件，用户可以从中选择CSV文件并将其列映射到数据字段。

$importer = new GridFieldImporter('before');
$gridConfig->addComponent($importer);

导入器使用CSVFieldMapper，它显示CSV的开始内容。

BulkLoaderSource

BulkLoaderSource提供迭代器以获取记录数据。数据可以来自任何地方，例如CSV文件、Web API等。

它可以独立于BulkLoader使用来获取数据。

$source = new CsvBulkLoaderSource();
$source->setFilePath("files/myfile.csv")
    ->setHasHeader(true)
    ->setFieldDelimiter(",")
    ->setFieldEnclosure("'");

foreach($source->getIterator() as $record){
    //do stuff
}

(更好的)BulkLoader

从特定源保存数据并通过ORM将其持久化到数据库。
确定哪些字段可以映射，可以是根据模型脚手架、配置提供或两者都提供。
检测现有记录，并根据标准跳过或更新它们。
根据给定的映射将源数据映射到新/现有DataObject。
查找、创建并连接关系对象到对象。
可以在处理之前清除所有记录。

$source = new CsvBulkLoaderSource();
$source->setFilePath("files/myfile.csv");

$loader = new BetterBulkLoader("Product");
$loader->setSource($source);
$loader->addNewRecords = false;  // an option to skip new records

$result = $loader->load();

ListBulkLoader

通常您会希望将批量加载限制在特定的DataList中。ListBulkLoader是BulkLoader的一种变体，它从给定的DataList中添加和删除记录。当然，DataList本身没有实现add方法，所以您可能会发现它对HasManyList更有用。

$category = ProductCategory::get()->first();

$source = new CsvBulkLoaderSource();
$source->setFilePath("productlist.csv");

$loader = new ListBulkLoader($category->Products());
$loader->setSource($source);

$result = $loader->load();

将记录数据映射到标准格式

您可以提供columnMap将传入的记录映射到标准格式。

$loader->columnMap = array(
    'first name' => 'FirstName',
    'Name' => 'FirstName',
    'bio' => 'Biography',
    'bday' => 'Birthday',
    'teamtitle' => 'Team.Title',
    'teamsize' => 'Team.TeamSize',
    'salary' => 'Contract.Amount'
);

此列映射由GridFieldImporter组件内的CSVFieldMapper控件生成。

脚手架与定义可映射字段

如果没有自己定义，可映射字段将进行脚手架搭建。这包括关系上的字段，以便关系可以连接起来。

可能存在您不想映射的字段，在这种情况下，您应在加载器上指定mappableFields数组。

$loader->mappableFields = array(
    'FirstName' => 'First Name',
    'Surname' => 'Last Name',
    'Biography' => 'Biography',
    'Birthday' => 'Birthday',
    'Team.Title' => 'Team'
);

转换传入的记录数据

您可能想对传入的记录数据进行一些转换。这可以通过指定针对记录字段名称的回调来实现。

$loader->transforms = array(
    'Code' => array(
        'callback' => function($value, $placeholder) {
            //capitalize course codes
            return strtoupper($value);
        }
    )
);

需要特定数据存在

缺少所需数据的记录将被跳过。

$loader->transforms = array(
    'Title' => array(
        'required' => true
    )
);

请注意，默认情况下会跳过空记录。

创建和关联相关DataObjects

批量加载器可以通过提供回调函数或使用Relation.FieldName风格的“点表示法”来处理关联对象的链接和创建。关联处理也在transformations数组中执行。

您可以在批量加载器级别指定是否创建和链接记录，然后您还可以指定每个字段的操作行为。默认行为是同时链接和创建关系对象。

以下是一些配置示例

$loader->transforms = array(
    //link and create courses
    'Course.Title' = array(
        'link' => true,
        'create' => true
    ),
    //only link to existing tutors
    'Tutor.Name' => array(
        'link' => true,
        'create' => false
    ),
    //custom way to find parent courses
    'Parent' => array(
        'callback' => function($value, $placeholder) use ($self){
            return Course::get()
                ->filter("Title", $value)
                ->first();
        }
    )
);

请注意，以上示例中的$placeholder指的是一个用于保存或检查重复项的占位符DataObject。您不应该在回调函数中调用$placeholder->write()。

指定关系列表

与您可能使用ListBulkLoader来限制记录到给定的DataList一样，您可能还想将关系记录限制到列表中。

$loader->transforms = array(
    //link and create courses
    'Course.Title' = array(
        'list' => $self->Courses()
    )
);

确定何时覆盖现有（重复）DataObjects

在标准化形式中映射记录数据时，会执行重复检查。

您可以对数据字段执行重复检查

//course is a duplicate when title is the same
$loader->duplicateChecks = array(
    "Title"
);

或对关系进行重复检查

//course selection is a duplicate when course is the same
$loader->duplicateChecks = array(
    "Course.Title"
);

也可以使用回调函数找到重复项

$loader->duplicateChecks = array(
    "FooBar" => array(
        "callback" => function($fieldName, $record) {
            if(!isset($record["FirstName"]) || !isset($record["LastName"])){
                return null;
            }

            return Person::get()
                ->filter("FirstName", $record['FirstName'])
                ->filter("LastName", $record['LastName'])
                ->first();
        }
    )
);

在导入期间发布页面

如果您正在导入SiteTree实例，您可以使用此配置自动发布这些页面

$loader->setPublishPages(true);

替换所有“遗留”ModelAdmin导入器

一些简单的yaml配置选项，有助于替换所有导入功能。

ModelAdmin:
    removelegacyimporters: true
    addbetterimporters: true

仅删除已设置的（非自定义）导入器

ModelAdmin:
    removelegacyimporters: scaffolded

故障排除

缺少关系对象

如果您在加载过程中编写关系对象，并且它们未通过验证，则加载器将简单地忽略该关系对象。

多个关系数据字段未映射到同一关系

如果您已将多个字段映射到同一关系，则可能会遇到错误地连接到现有关系对象的情况。第一个映射的字段与用于查找关系的字段相同。例如，您可能希望使用标题来查找/创建关系，然后添加金额到该关系，而不是通过金额查找/创建关系并设置标题。

使用可映射字段数组定义正确的顺序以修复此问题。

贡献

请尽可能为此模块做出贡献。查看问题和里程碑，以查看需要做什么。

许可

MIT

作者

Jeremy Shipman (http://jeremyshipman.com)

i-lateral / silverstripe-importexport

维护者

详细信息