<?php

namespace Kylin\Excel\Exceptions;

use Exception;

/**
 * Excel异常类
 * 
 * 用于处理Excel导入导出过程中可能出现的各种异常情况
 */
class ExcelException extends Exception
{
    /**
     * 文件未找到异常
     * 
     * @param string $path 文件路径
     * @return self
     */
    public static function fileNotFound(string $path): self
    {
        return new self("Excel文件未找到: {$path}");
    }

    /**
     * 无效的文件扩展名异常
     * 
     * @param string $extension 文件扩展名
     * @return self
     */
    public static function invalidExtension(string $extension): self
    {
        return new self("无效的文件扩展名: {$extension}。仅支持 xlsx、xls、csv 格式。");
    }

    /**
     * 工作表未找到异常
     * 
     * @param string|int $sheet 工作表名称或索引
     * @return self
     */
    public static function sheetNotFound(string|int $sheet): self
    {
        return new self("工作表未找到: {$sheet}");
    }

    /**
     * 导出失败异常
     * 
     * @param string $message 错误信息
     * @return self
     */
    public static function exportFailed(string $message): self
    {
        return new self("导出失败: {$message}");
    }

    /**
     * 导入失败异常
     * 
     * @param string $message 错误信息
     * @return self
     */
    public static function importFailed(string $message): self
    {
        return new self("导入失败: {$message}");
    }

    /**
     * 扩展未加载异常
     * 
     * @return self
     */
    public static function extensionNotLoaded(): self
    {
        return new self('xlswriter扩展未加载，请先安装该扩展。');
    }
}
