<?php

namespace Kylin\Excel;

/**
 * Excel门面类
 * 
 * 提供静态方法用于Excel文件的导入、导出、下载等操作
 * 该类作为Excel服务的外观模式，简化了Excel操作的调用方式
 */
class Excel
{
    /**
     * 导入Excel文件
     * 
     * 将Excel文件中的数据导入到指定的导入对象中
     * 
     * @param object $import 导入对象，需实现相应的导入接口（如ToModel、ToCollection等）
     * @param string $filePath Excel文件路径
     * @param string|null $disk 存储磁盘名称，如'local'、'public'等，默认为null表示使用本地路径
     * @param string|null $readerType 读取器类型，如'xlsx'、'xls'、'csv'等，默认自动检测
     * @return void
     * 
     * @example
     * // 导入Excel到模型
     * Excel::import(new UsersImport, 'users.xlsx');
     */
    public static function import(object $import, string $filePath, ?string $disk = null, ?string $readerType = null): void
    {
        app('excel')->import($import, $filePath, $disk, $readerType);
    }

    /**
     * 导出Excel文件到存储
     * 
     * 将数据导出为Excel文件并存储到指定路径
     * 
     * @param object $export 导出对象，需实现相应的导出接口（如FromCollection、FromArray等）
     * @param string $filePath 导出文件的存储路径
     * @param string|null $disk 存储磁盘名称，默认为null表示使用本地路径
     * @param string|null $writerType 写入器类型，如'xlsx'、'xls'、'csv'等，默认为xlsx
     * @return bool 返回导出是否成功
     * 
     * @example
     * // 导出用户数据到Excel
     * Excel::export(new UsersExport, 'exports/users.xlsx');
     */
    public static function export(object $export, string $filePath, ?string $disk = null, ?string $writerType = null): bool
    {
        return app('excel')->store($export, $filePath, $disk, $writerType);
    }

    /**
     * 下载Excel文件
     * 
     * 将数据导出为Excel文件并直接下载到浏览器
     * 
     * @param object $export 导出对象，需实现相应的导出接口
     * @param string $fileName 下载时显示的文件名
     * @param string|null $writerType 写入器类型，默认为xlsx
     * @return void
     * 
     * @example
     * // 下载用户数据Excel
     * return Excel::download(new UsersExport, 'users.xlsx');
     */
    public static function download(object $export, string $fileName, ?string $writerType = null): void
    {
        app('excel')->download($export, $fileName, $writerType);
    }

    /**
     * 存储Excel文件
     * 
     * 将数据导出为Excel文件并存储到指定路径
     * 
     * @param object $export 导出对象，需实现相应的导出接口
     * @param string $filePath 导出文件的存储路径
     * @param string|null $disk 存储磁盘名称，默认为null表示使用本地路径
     * @param string|null $writerType 写入器类型，默认为xlsx
     * @return bool 返回存储是否成功
     * 
     * @example
     * // 存储Excel到指定磁盘
     * Excel::store(new UsersExport, 'exports/users.xlsx', 's3');
     */
    public static function store(object $export, string $filePath, ?string $disk = null, ?string $writerType = null): bool
    {
        return app('excel')->store($export, $filePath, $disk, $writerType);
    }

    /**
     * 将Excel数据读取为集合
     * 
     * 读取Excel文件内容并转换为Laravel Collection对象
     * 
     * @param object $import 导入对象，用于定义读取规则
     * @param string $filePath Excel文件路径
     * @param string|null $disk 存储磁盘名称，默认为null
     * @param string|null $readerType 读取器类型，默认自动检测
     * @return \Illuminate\Support\Collection 返回包含Excel数据的集合
     * 
     * @example
     * // 读取Excel为集合
     * $collection = Excel::toCollection(new UsersImport, 'users.xlsx');
     */
    public static function toCollection(object $import, string $filePath, ?string $disk = null, ?string $readerType = null): \Illuminate\Support\Collection
    {
        return app('excel')->toCollection($import, $filePath, $disk, $readerType);
    }

    /**
     * 将Excel数据读取为数组
     * 
     * 读取Excel文件内容并转换为PHP数组
     * 
     * @param object $import 导入对象，用于定义读取规则
     * @param string $filePath Excel文件路径
     * @param string|null $disk 存储磁盘名称，默认为null
     * @param string|null $readerType 读取器类型，默认自动检测
     * @return array 返回包含Excel数据的数组
     * 
     * @example
     * // 读取Excel为数组
     * $data = Excel::toArray(new UsersImport, 'users.xlsx');
     */
    public static function toArray(object $import, string $filePath, ?string $disk = null, ?string $readerType = null): array
    {
        return app('excel')->toArray($import, $filePath, $disk, $readerType);
    }

    /**
     * 获取Excel原始内容
     * 
     * 将导出数据转换为Excel文件的原始二进制内容
     * 
     * @param object $export 导出对象，需实现相应的导出接口
     * @param string|null $writerType 写入器类型，默认为xlsx
     * @return string 返回Excel文件的原始二进制内容
     * 
     * @example
     * // 获取Excel原始内容
     * $content = Excel::raw(new UsersExport);
     * 
     * // 可用于自定义响应
     * return response($content)->header('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
     */
    public static function raw(object $export, ?string $writerType = null): string
    {
        return app('excel')->raw($export, $writerType);
    }

    /**
     * 队列导出Excel
     * 
     * 将Excel导出任务放入队列异步执行，适用于大数据量导出
     * 
     * @param object $export 导出对象，需实现相应的导出接口
     * @param string $filePath 导出文件的存储路径
     * @param string|null $disk 存储磁盘名称，默认为null
     * @return void
     * 
     * @example
     * // 异步导出大量数据
     * Excel::queue(new LargeDataExport, 'exports/large_data.xlsx');
     */
    public static function queue(object $export, string $filePath, ?string $disk = null): void
    {
        app('excel')->queue($export, $filePath, $disk);
    }
}
