<?php

namespace Kylin\Sms\Exceptions;

use Exception;

/**
 * 短信异常基类
 * 
 * 所有短信相关异常的基类，提供统一的异常处理机制
 * 包含错误上下文信息，便于调试和日志记录
 * 
 * @package Kylin\Sms\Exceptions
 */
class SmsException extends Exception
{
    /**
     * 异常上下文信息
     * 
     * 存储与异常相关的额外信息，如请求参数、响应数据等
     * 用于调试和日志记录
     * 
     * @var array
     */
    protected array $context = [];

    /**
     * 构造函数
     * 
     * 创建短信异常实例
     * 
     * @param string $message 异常消息
     * @param int $code 错误代码，默认为 0
     * @param array $context 异常上下文信息，默认为空数组
     * @param Exception|null $previous 前一个异常，用于异常链，默认为 null
     */
    public function __construct(string $message = '', int $code = 0, array $context = [], ?Exception $previous = null)
    {
        parent::__construct($message, $code, $previous);
        $this->context = $context;
    }

    /**
     * 获取异常上下文信息
     * 
     * 返回与异常相关的上下文数据，便于调试
     * 
     * @return array 上下文信息数组
     */
    public function getContext(): array
    {
        return $this->context;
    }

    /**
     * 设置异常上下文信息
     * 
     * 允许在异常创建后设置或更新上下文信息
     * 
     * @param array $context 上下文信息数组
     * @return self 支持链式调用
     */
    public function setContext(array $context): self
    {
        $this->context = $context;
        return $this;
    }
}
