bagisto-data-transfer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data Transfer

数据传输

packages/Webkul/DataTransfer

moves bulk records into Bagisto from a file. The package ships three importers — products, customers and tax rates — and a queued pipeline that validates, imports, links and indexes in batches.

Import only. There is no exporter here; a DataGrid's own export handles outbound data — see the

bagisto-datagrid-development

skill.

packages/Webkul/DataTransfer

用于将批量记录从文件导入到 Bagisto 系统中。该包内置了三个导入器——产品、客户和税率——以及一个队列化处理流程，可批量完成验证、导入、关联和索引操作。

仅支持导入。此包不包含导出功能；数据导出由 DataGrid 自身的导出功能处理——详情请参考

bagisto-datagrid-development

技能文档。

Reference files

参考文件

File	Load when
importers.md	Writing or changing an Importer — the contract, validation, batches
pipeline.md	The state machine, queued jobs, and debugging a stuck import

文件	适用场景
importers.md	编写或修改 Importer 类——包括契约、验证、批量处理逻辑
pipeline.md	状态机、队列任务，以及调试卡住的导入流程

The registry

注册表

An importer is registered in

Config/importers.php

, merged into the top-level importers
key (not

data_transfer.importers

php

'tax_rates' => [
    'title'        => 'data_transfer::app.importers.tax-rates.title',
    'importer'     => 'Webkul\DataTransfer\Helpers\Importers\TaxRate\Importer',
    'sample_paths' => [
        'csv'  => 'bagisto-data-transfer/samples/csv/tax-rates.csv',
        'xls'  => 'bagisto-data-transfer/samples/xls/tax-rates.xls',
        'xlsx' => 'bagisto-data-transfer/samples/xlsx/tax-rates.xlsx',
        'xml'  => 'bagisto-data-transfer/samples/xml/tax-rates.xml',
    ],
],

The admin create/edit screens iterate

config('importers')

directly, so a new entry appears in the type dropdown with no view change.

Import

resolves the class with

config('importers.'.$type.'.importer')

— the array key is the

type

stored on the import record, so renaming a key orphans existing imports.

Provide all four sample paths. The UI offers a sample download per format, and a missing file is a broken link rather than a graceful fallback.

导入器需在

Config/importers.php

中注册，并合并到顶层的 importers
键下（而非

data_transfer.importers

）：

php

'tax_rates' => [
    'title'        => 'data_transfer::app.importers.tax-rates.title',
    'importer'     => 'Webkul\DataTransfer\Helpers\Importers\TaxRate\Importer',
    'sample_paths' => [
        'csv'  => 'bagisto-data-transfer/samples/csv/tax-rates.csv',
        'xls'  => 'bagisto-data-transfer/samples/xls/tax-rates.xls',
        'xlsx' => 'bagisto-data-transfer/samples/xlsx/tax-rates.xlsx',
        'xml'  => 'bagisto-data-transfer/samples/xml/tax-rates.xml',
    ],
],

后台的创建/编辑页面会直接遍历

config('importers')

，因此新增的条目会直接显示在类型下拉菜单中，无需修改视图。

Import

类通过

config('importers.'.$type.'.importer')

解析对应的导入器类——数组的键会作为导入记录的

type

字段存储，因此修改键名会导致现有导入记录失效。

需提供全部四种格式的示例文件路径。UI 会为每种格式提供示例文件下载链接，若文件缺失会导致链接失效，而非优雅降级。

The importer contract

导入器契约

Extend

Helpers\Importers\AbstractImporter

and implement exactly two methods:

php

abstract public function validateRow(array $rowData, int $rowNumber): bool;
abstract public function importBatch(ImportBatchContract $importBatchContract): bool;

Everything else is declared as properties —

$validColumnNames

$masterAttributeCode

$permanentAttributes

$messages

— or overridden as hooks. See importers.md.

需继承

Helpers\Importers\AbstractImporter

并实现以下两个方法：

php

abstract public function validateRow(array $rowData, int $rowNumber): bool;
abstract public function importBatch(ImportBatchContract $importBatchContract): bool;

其余逻辑均通过属性声明——如

$validColumnNames

、

$masterAttributeCode

、

$permanentAttributes

、

$messages

——或重写钩子方法实现。详情请参考 importers.md。

Sources

数据源

Helpers\Sources\

supplies

CSV

XLS

XLSX

and

XML

, all extending

AbstractSource

, which is an iterator over rows plus

generateErrorReport(array $errors)

. An importer never opens the file itself — it reads

$this->source

, so the same importer serves every format.

Helpers\Sources\

目录下提供了

CSV

、

XLS

、

XLSX

和

XML

四种数据源类，均继承自

AbstractSource

，该类是行数据的迭代器，并提供

generateErrorReport(array $errors)

方法。导入器无需自行打开文件——它通过读取

$this->source

获取数据，因此同一个导入器可支持所有格式。

Non-negotiables

硬性要求

Rows are validated before anything is written.
```
validateRow()
```
must be free of side effects: it runs over the whole file, and on
```
stop-on-errors
```
the import may never reach
```
importBatch()
```
.
Work in batches, never row-by-row over the whole file.
```
AbstractImporter::BATCH_SIZE
```
is 100 and the pipeline dispatches one job per batch. An importer that loads the file into memory defeats the design and fails on the file sizes this feature exists for.
Go through repositories for writes, as everywhere else in Bagisto.
Every message goes through
trans()
in the
```
data_transfer::
```
namespace, in all 22 locales.
Declare
isLinkingRequired()
/
isIndexingRequired()
honestly. Returning true adds a queued stage per batch; returning false when linking is needed leaves records half-related with no error.
The queue must be running for anything past validation. With
```
QUEUE_CONNECTION=sync
```
the whole import runs inline in the request and will time out on a real file.

REQUIRED SUB-SKILL: Use bagisto-change-verification before calling any change done.

写入数据前必须先验证所有行。
```
validateRow()
```
方法不得产生副作用：它会遍历整个文件，若开启
```
stop-on-errors
```
模式，导入流程可能永远不会执行到
```
importBatch()
```
。
必须批量处理，绝不能逐行遍历整个文件。
```
AbstractImporter::BATCH_SIZE
```
的默认值为 100，处理流程会为每个批次分配一个队列任务。若导入器将整个文件加载到内存中，会违背设计初衷，且在处理大文件时会失败。
写入操作必须通过仓库（repositories）完成，与 Bagisto 中的其他模块保持一致。
所有提示信息必须通过
trans()
方法从
data_transfer::
命名空间获取，并支持全部22种语言环境。
必须如实声明
isLinkingRequired()
/
isIndexingRequired()
。返回
```
true
```
会为每个批次添加一个队列处理阶段；若实际需要关联操作却返回
```
false
```
，会导致记录关联不完整且无错误提示。
队列服务必须处于运行状态，才能完成验证之后的所有操作。若设置
```
QUEUE_CONNECTION=sync
```
，整个导入流程会在请求内同步执行，处理真实文件时会超时。