Installation

安装

Install via Composer:

通过 Composer 安装：

composer require raise-studio/import

Register the Plugin

注册插件

Add the plugin to your PanelProvider to enable the Import Log resource (Pro):

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

use RaiseStudio\Import\RaiseImportPlugin;

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

Quick Start

快速开始

The simplest way to add import to any Filament table:

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

use RaiseStudio\Import\Actions\ImportAction;

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

Full Configuration

完整配置

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;
    });

Configuration

配置

Publish the config file:

发布配置文件：

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

Available options:

可用配置项：

// config/raise-import.php
'chunk_size' => 500,              // Rows per transaction
'duplicate_behavior' => 'skip',   // skip|update|error
'max_file_size' => 50,            // MB
'preview_limit' => 10,            // Preview rows
'allowed_extensions' => ['csv', 'xlsx', 'ods'],

// Pro license
'license_key' => env('RAISE_IMPORT_LICENSE_KEY'),
'license_verify_url' => env('RAISE_IMPORT_LICENSE_VERIFY_URL',
    'https://license.raise-studio.com/api/license/verify'
),

Requirements

环境要求

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

Field API

字段 API

Field::make('email')
    ->label('Email Address')       // Display label
    ->rules('email|unique:users') // Validation rules
    ->default('')                  // Default value
    ->options(['a','b','c'])      // Dropdown options
    ->required()                   // Mark as required

Pro Features

专业版功能

Pipeline System

管道系统

Add global and field-level pipes to transform data during import:

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

ImportAction::make()
    ->model(User::class)
    // Global pipes
    ->pipe(new TrimStringsPipe())
    ->pipe(new LowercasePipe())
    // Field-level pipes
    ->fieldPipe('password', new BcryptPipe())
    ->fieldPipe('birthday', new DateFormatPipe('Y-m-d'));

Import History

导入历史

Track every import with full CRUD, statistics, and error reports.

记录每次导入，支持完整 CRUD、统计和错误报告。

Queue Support

队列支持

Large imports (>5000 rows) are automatically dispatched to the queue. Configurable via queue.enabled and queue.threshold.

大数据量（>5000 行）自动分发到队列处理。通过 queue.enabled 和 queue.threshold 配置。

REST API

REST API

Pro edition includes 5 API endpoints (authenticated via auth middleware):

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

POST /raise-import/upload       # Upload file, get headers + preview
POST /raise-import/preview      # Preview mapped data
POST /raise-import/import       # Execute import
GET  /raise-import/template/{model}  # Download CSV template
GET  /raise-import/errors/{id}/download  # Download error report

Translations

翻译

Publish translations to customize or add new languages:

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

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

Built-in languages: English (en) and Simplified Chinese (zh_CN).

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