README

以各种形式（包括CSV）从SilverStripe导入和导出数据。该模块用作框架中找到的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本身没有实现添加方法，所以您可能会发现它对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
    )
);

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

创建和链接相关数据对象

批量加载器可以通过提供回调或使用Relation.FieldName风格的“点表示法”来处理链接和创建has_one关系对象。关系处理也在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是指一个用于保存或检查重复项的占位符数据对象。您不应该在回调中调用$placeholder->write()。

指定关系列表

您可以使用ListBulkLoader将记录约束到给定的数据列表中，同样，您也可能想将关系记录约束到列表中。

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

确定何时覆盖现有（重复）数据对象

重复检查是在记录数据上执行的，数据映射到标准化的形式。

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

//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

故障排除

缺少关系对象

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

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

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

使用mappableFields数组定义正确的顺序以解决这个问题。

贡献

请尽您所能为此模块做出贡献。查看问题和里程碑以了解需要完成的工作。

许可证

MIT

作者

Jeremy Shipman (http://jeremyshipman.com)

burnbright / silverstripe-importexport

维护者

详细信息