使用文档

安装

通过 Composer 安装：

composer require raise-studio/import

注册插件

在 PanelProvider 中添加插件，启用导入历史功能（专业版）：

use RaiseStudio\Import\RaiseImportPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(RaiseImportPlugin::make());
}

快速开始

给任何 Filament 表格添加导入功能的最简方式：

use RaiseStudio\Import\Actions\ImportAction;

public static function table(Table $table): Table
{
    return $table
        ->headerActions([
            ImportAction::make()
                ->model(User::class),
        ]);
}

完整配置

ImportAction::make('import')
    ->model(User::class)
    ->label('Import Users')
    ->fields([
        Field::make('name')->label('Name')->required(),
        Field::make('email')->label('Email')->rules('email|unique:users'),
        Field::make('phone')->label('Phone')->rules('numeric'),
    ])
    ->uniqueBy('email')
    ->onDuplicate('skip')
    ->chunkSize(500)
    ->rules([
        'name' => 'required|string|max:100',
        'email' => 'email|max:255',
    ])
    ->mutateBeforeCreate(function (array $row) {
        $row['password'] = bcrypt('default123');
        return $row;
    });

配置

发布配置文件：

php artisan vendor:publish --tag=raise-import-config

可用配置项（config/raise-import.php）：

'chunk_size' => 500,              // 每事务处理行数
'duplicate_behavior' => 'skip',   // skip | update | error
'max_file_size' => 50,            // MB
'preview_limit' => 10,            // 预览行数
'allowed_extensions' => ['csv', 'xlsx', 'ods'],

// 专业版授权
'license_key' => env('RAISE_IMPORT_LICENSE_KEY'),
'license_verify_url' => env('RAISE_IMPORT_LICENSE_VERIFY_URL',
    'https://license.raise-studio.com/api/license/verify'
),

环境要求

• PHP 8.1+
• Filament 4.x 或 5.x
• Livewire 3.x（Filament 4）或 4.x（Filament 5）

字段 API

Field::make('email')
    ->label('Email Address')       // 显示标签
    ->rules('email|unique:users')  // 验证规则
    ->default('')                   // 默认值
    ->options(['a', 'b', 'c'])     // 下拉选项
    ->required();                   // 标记为必填

专业版功能

管道系统

添加全局和字段管道，在导入过程中转换数据：

ImportAction::make()
    ->model(User::class)
    // 全局管道 — 应用到每一行
    ->pipe(new TrimStringsPipe())
    ->pipe(new LowercasePipe())
    // 字段管道 — 只应用到指定列
    ->fieldPipe('password', new BcryptPipe())
    ->fieldPipe('birthday', new DateFormatPipe('Y-m-d'));

导入历史

记录每次导入，支持完整 CRUD、统计和错误报告。通过 RaiseImportPlugin 注册的导入历史资源页面查看。

队列支持

大数据量（>5,000 行）自动分发到队列处理。可通过以下配置调整：

'queue.enabled' => true,
'queue.threshold' => 5000,

REST API

专业版包含 5 个 API 端点（通过 auth 中间件认证）：

翻译

发布翻译文件以自定义或添加新语言：

php artisan vendor:publish --tag=raise-import-translations

内置语言：英文（en）和简体中文（zh_CN）。