تابع xml_get_error_code() در PHP

تابع xml_get_error_code() بخشی از مجموعه توابع Expat-based XML parser در PHP است و برای دریافت «کد خطا» آخرین عملیات تجزیه (parse) روی یک پارسر XML به‌کار می‌رود. این تابع وقتی مفید است که xml_parse() یا توابع مرتبط با xml_parser_* خطا برگردانند و شما بخواهید اطلاعات دقیق‌تری درباره نوع خطا داشته باشید.

چرا و چه زمانی از xml_get_error_code() استفاده کنیم؟

• برای گزارش و لاگ کردن خطای دقیق هنگام پردازش XML.
• در پردازش‌های event-driven یا استریم (مثلاً هنگام خواندن فایلی بزرگ) که با xml_parser_create کار می‌کنید.
• برای نمایش پیام دوستانه به کاربر یا تبدیل خطا به کد وضعیت HTTP در APIها.

امضای تابع و مقدار بازگشتی

امضای تابع به شکل زیر است:

int xml_get_error_code ( resource $parser )

تابع یک عدد صحیح (int) برمی‌گرداند که نمایانگر یکی از ثابت‌های XML_ERROR_* است. مقدار 0 معمولاً به معنی XML_ERROR_NONE و عدم وجود خطا است.

نمونه ساده: گرفتن کد خطا، پیغام و موقعیت

<?php
$xml = "<root><item></root>"; // تگ مطابقی وجود ندارد
$parser = xml_parser_create();

if (!xml_parse($parser, $xml, true)) {
    $code = xml_get_error_code($parser);
    $message = xml_error_string($code);
    $line = xml_get_current_line_number($parser);
    $col = xml_get_current_column_number($parser);

    echo "Error code: $coden";
    echo "Message: $messagen";
    echo "Line: $line, Column: $coln";
}

xml_parser_free($parser);
?>

توضیح: در این مثال، یک XML ناقص به parser داده می‌شود. اگر xml_parse() خطا برگرداند، با xml_get_error_code() کد خطا گرفته می‌شود، سپس با xml_error_string() پیام قابل خواندن از روی آن کد استخراج می‌شود و در نهایت با xml_get_current_line_number() و xml_get_current_column_number() موقعیت خطا مشخص می‌گردد. در انتها باید با xml_parser_free() منبع parser آزاد شود.

نمونه کاربردی: تولید آرایه خطا برای API

<?php
function parseXmlAndReport($xmlString) {
    $parser = xml_parser_create();
    xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

    if (!xml_parse($parser, $xmlString, true)) {
        $code = xml_get_error_code($parser);
        $message = xml_error_string($code);
        $line = xml_get_current_line_number($parser);
        $col = xml_get_current_column_number($parser);
        xml_parser_free($parser);

        return [
            'success' => false,
            'error_code' => $code,
            'error_message' => $message,
            'line' => $line,
            'column' => $col
        ];
    }

    xml_parser_free($parser);
    return ['success' => true];
}

توضیح: این تابع یک ورودی XML می‌گیرد و تلاش می‌کند آن را parse کند. در صورت خطا، اطلاعات کامل شامل کد و پیام و موقعیت را برمی‌گرداند که برای APIها یا لاگ‌ها مناسب است.

ثابت‌های رایج خطا (نمونه)

در جدول زیر چند ثابت متداول و توضیح کوتاه‌شان آمده است. لیست کامل در مستندات PHP و libexpat قابل مشاهده است؛ نام‌ها و مقادیر ممکن است بین نسخه‌ها تفاوت اندکی داشته باشند.

نکات عملی و نکات فنی

• xml_get_error_code() برای پارسرهای Expat (xml_parser_create و توابع مرتبط) کاربرد دارد. اگر از DOMDocument یا SimpleXML (بر مبنای libxml) استفاده می‌کنید، باید از libxml_get_errors() و libxml_get_last_error() استفاده کنید.
• همیشه پس از اتمام کار با پارسر، xml_parser_free() را فراخوانی کنید تا منابع آزاد شوند.
• برای نمایش پیام به کاربر بهتر است علاوه بر کد خطا، خط و ستون خطا را نیز نشان دهید تا خطا سریع‌تر قابل رفع باشد.
• کدهای XML_ERROR_* می‌توانند بسته به نسخه libexpat متفاوت باشند؛ لذا برای چک کردن وجود یک نوع خاص خطا بهتر است از مقایسه با ثابت‌ها استفاده کنید نه عدد خام.

مثال پیشرفته — نگاشت خطا به پاسخ HTTP

<?php
$result = parseXmlAndReport($inputXml);
if (!$result['success']) {
    // نمونه نگاشت ساده به کد وضعیت HTTP
    $status = ($result['error_code'] === XML_ERROR_NO_MEMORY) ? 500 : 400;
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($result, JSON_UNESCAPED_UNICODE);
    exit;
}
// ادامه پردازش در صورت موفقیت
?>

توضیح: این کد نشان می‌دهد که چگونه می‌توان بسته به نوع خطا، پاسخ HTTP مناسبی ارسال کرد. به عنوان مثال خطای کمبود حافظه ممکن است 500 (خطای سرور) و خطاهای نحوی 400 (درخواست نادرست) بازگردانده شوند.

چه زمانی بهتر است از روش‌های دیگر استفاده کنیم؟

• اگر نیاز به بررسی دقیق اسناد XML با اعتبارسنجی XSD یا امکانات پیشرفته‌تر دارید، استفاده از DOMDocument یا XMLReader همراه با libxml پیشنهاد می‌شود.
• برای فایل‌های خیلی بزرگ یا پردازش جریان (stream) XML، xml_parser_create و توابع مربوطه (به همراه xml_get_error_code) مناسب و کارا هستند چون حافظه کمتری مصرف می‌کنند.

جمع‌بندی: xml_get_error_code() ابزاری ساده و مؤثر برای به‌دست آوردن کد خطا در پارسر Expat در PHP است. ترکیب آن با xml_error_string() و توابع موقعیت‌یابی (خط و ستون) باعث می‌شود تا خطاها سریع‌تر تشخیص و رفع شوند و برای لاگ و پاسخ‌دهی به‌صورت مناسب استفاده شوند.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال