# Kylin Excel Package

一个基于 xlswriter 扩展的高性能 Excel 导入导出包，为 Laravel 应用提供简洁易用的 Excel 操作功能。

## 功能特性

- ✅ 高性能：基于 xlswriter 扩展，支持大数据量处理
- ✅ 丰富的导入导出接口
- ✅ 支持多工作表导出
- ✅ 支持队列异步处理
- ✅ 完整的事件系统
- ✅ 数据验证集成
- ✅ 支持多种数据源
- ✅ 支持 Laravel 存储磁盘

## 安装

### 1. 安装 xlswriter 扩展

```bash
# Linux/macOS
extension=xlswriter.so

# Windows
# 在 php.ini 中添加
;extension=xlswriter.dll
```

### 2. 安装包

```bash
composer require kylin/excel
```

### 3. 注册服务提供者

在 `config/app.php` 中添加：

```php
'providers' => [
    // ...
    Kylin\Excel\ExcelServiceProvider::class,
],

'aliases' => [
    // ...
    'Excel' => Kylin\Excel\Facades\Excel::class,
],
```

## 快速开始

### 导出示例

#### 从集合导出

```php
use Kylin\Excel\Concerns\FromCollection;
use Kylin\Excel\Concerns\WithHeadings;

class UsersExport implements FromCollection, WithHeadings
{
    public function collection()
    {
        return User::all();
    }

    public function headings(): array
    {
        return ['ID', '姓名', '邮箱', '创建时间'];
    }
}

// 下载
Excel::download(new UsersExport, 'users.xlsx');

// 存储
Excel::store(new UsersExport, 'exports/users.xlsx');

// 存储到指定磁盘
Excel::store(new UsersExport, 'exports/users.xlsx', 's3');
```

#### 从数组导出

```php
use Kylin\Excel\Concerns\FromArray;

class ArrayExport implements FromArray
{
    public function array(): array
    {
        return [
            ['1', '张三', 'zhangsan@example.com'],
            ['2', '李四', 'lisi@example.com'],
        ];
    }
}
```

#### 从查询导出

```php
use Kylin\Excel\Concerns\FromQuery;

class QueryExport implements FromQuery
{
    public function query()
    {
        return User::query();
    }
}
```

#### 多工作表导出

```php
use Kylin\Excel\Concerns\WithMultipleSheets;

class MultiSheetExport implements WithMultipleSheets
{
    public function sheets(): array
    {
        return [
            new UsersExport(),
            new OrdersExport(),
        ];
    }
}
```

### 导入示例

#### 导入到集合

```php
use Kylin\Excel\Concerns\ToCollection;

class UsersImport implements ToCollection
{
    public function collection(Collection $collection)
    {
        foreach ($collection as $row) {
            User::create([
                'name' => $row[0],
                'email' => $row[1],
            ]);
        }
    }
}

Excel::import(new UsersImport, 'users.xlsx');
```

#### 导入到模型

```php
use Kylin\Excel\Concerns\ToModel;

class UsersImport implements ToModel
{
    public function model(array $row)
    {
        return new User([
            'name' => $row[0],
            'email' => $row[1],
        ]);
    }
}
```

#### 带验证的导入

```php
use Kylin\Excel\Concerns\ToModel;
use Kylin\Excel\Concerns\WithValidation;

class UsersImport implements ToModel, WithValidation
{
    public function model(array $row)
    {
        return new User([
            'name' => $row['name'],
            'email' => $row['email'],
        ]);
    }

    public function rules(): array
    {
        return [
            'name' => 'required',
            'email' => 'required|email|unique:users',
        ];
    }

    public function customAttributes(): array
    {
        return [
            'name' => '姓名',
            'email' => '邮箱',
        ];
    }
}
```

## 高级功能

### 数据映射

```php
use Kylin\Excel\Concerns\FromCollection;
use Kylin\Excel\Concerns\WithMapping;

class UsersExport implements FromCollection, WithMapping
{
    public function collection()
    {
        return User::all();
    }

    public function map($user): array
    {
        return [
            $user->id,
            $user->name,
            $user->email,
            $user->created_at->format('Y-m-d H:i:s'),
        ];
    }
}
```

### 列格式化

```php
use Kylin\Excel\Concerns\WithColumnFormatting;

class UsersExport implements FromCollection, WithColumnFormatting
{
    // ...

    public function columnFormats(): array
    {
        return [
            'C' => '0.00', // 货币格式
            'D' => 'yyyy-mm-dd', // 日期格式
        ];
    }
}
```

### 事件系统

```php
use Kylin\Excel\Concerns\WithEvents;
use Kylin\Excel\Events\AfterImport;
use Kylin\Excel\Events\BeforeImport;

class UsersImport implements ToModel, WithEvents
{
    // ...

    public function registerEvents(): array
    {
        return [
            BeforeImport::class => function (BeforeImport $event) {
                // 导入前的逻辑
            },
            AfterImport::class => function (AfterImport $event) {
                // 导入后的逻辑
            },
        ];
    }
}
```

### 队列处理

```php
use Kylin\Excel\Concerns\ShouldQueue;

class LargeDataExport implements FromQuery, ShouldQueue
{
    public function query()
    {
        return User::query();
    }
}

// 队列导出
Excel::queue(new LargeDataExport, 'exports/large_data.xlsx');

// 队列导入
class LargeDataImport implements ToModel, ShouldQueue
{
    // ...
}

Excel::import(new LargeDataImport, 'imports/large_data.xlsx');
```

## 支持的接口

### 导出接口
- `FromArray` - 从数组导出
- `FromCollection` - 从集合导出
- `FromQuery` - 从查询导出
- `WithHeadings` - 定义标题行
- `WithMapping` - 数据映射
- `WithColumnFormatting` - 列格式化
- `WithCustomStartCell` - 自定义起始单元格
- `WithTitle` - 工作表标题
- `WithMultipleSheets` - 多工作表
- `WithEvents` - 事件注册
- `ShouldQueue` - 队列处理

### 导入接口
- `ToModel` - 导入到模型
- `ToCollection` - 导入到集合
- `ToArray` - 导入到数组
- `WithHeadingRow` - 标记标题行
- `WithValidation` - 数据验证
- `WithChunkReading` - 分块读取
- `WithLimit` - 读取限制
- `WithEvents` - 事件注册
- `ShouldQueue` - 队列处理

## 错误处理

```php
try {
    Excel::import(new UsersImport, 'users.xlsx');
} catch (\Kylin\Excel\Exceptions\ExcelException $e) {
    // 处理错误
    echo $e->getMessage();
}
```

## 系统要求

- PHP 8.5+
- Laravel 12.0+
- xlswriter 扩展

## 许可证

MIT License