تابع xml_parser_set_option() در PHP

تابع xml_parser_set_option() برای تنظیم گزینه‌های مربوط به تجزیه‌گر XML در PHP استفاده می‌شود. این تابع به شما اجازه می‌دهد رفتار تجزیه‌گر SAX (که با توابعی مثل xml_parse() و xml_set_element_handler() کار می‌کند) را تغییر دهید؛ مثلاً نگهداری حروف بزرگ/کوچک برچسب‌ها یا تعیین رمزگذاری خروجی. در این مقاله با مثال‌های عملی، نکات فنی و بهترین شیوه‌ها آشنا می‌شویم.

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

کنترل شکل و فرمت رشته‌هایی که به callbackها ارسال می‌شود.
حفظ یا تبدیل حالت حروف برچسب‌ها (case folding).
تطبیق رمزگذاری ورودی/خروجی برای جلوگیری از مشکلات کاراکتری.
بهینه‌سازی و سازگاری پردازش XML با نیازهای برنامه.

پارامترها و مقدار بازگشتی

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

bool xml_parser_set_option(resource $parser, int $option, mixed $value)

پارامترها:

$parser: شناسه تجزیه‌گر که با xml_parser_create() ایجاد شده.
$option: یکی از ثوابت مربوط به گزینه‌ها (مثلاً XML_OPTION_CASE_FOLDING).
$value: مقدار موردنظر برای آن گزینه (عدد، boolean یا رشته بسته به گزینه).

تابع مقدار بولی بازمی‌گرداند (true در صورت موفقیت، false در غیر این صورت).

گزینه‌های رایج

گزینه	نوع مقدار	توضیح
XML_OPTION_CASE_FOLDING	bool	اگر true باشد (پیش‌فرض) نام تگ‌ها به حروف بزرگ تبدیل می‌شوند؛ با false می‌توان حالت حروف را حفظ کرد.
XML_OPTION_TARGET_ENCODING	string	رمزگذاری خروجی که رشته‌های callback در آن بازگردانده می‌شوند (مثلاً “UTF-8”).

نکته: برخی گزینه‌های دیگر ممکن است در نسخه‌های مختلف PHP یا پیاده‌سازی‌های خاص libxml متفاوت باشند؛ برای اطمینان به مستندات PHP/نسخه خود مراجعه کنید.

مثال عملی 1 — حفظ حروف کوچک در نام تگ‌ها

<?php
$xml = '<root><Child>Hello</Child></root>';
$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

function startElement($parser, $name, $attrs) {
    echo "Start: $namen";
}
function endElement($parser, $name) {
    echo "End: $namen";
}

xml_set_element_handler($parser, "startElement", "endElement");

if (!xml_parse($parser, $xml, true)) {
    printf("XML Error: %s at line %dn",
        xml_error_string(xml_get_error_code($parser)),
        xml_get_current_line_number($parser));
}
xml_parser_free($parser);
?>

توضیح: در این مثال ابتدا یک تجزیه‌گر می‌سازیم و سپس با xml_parser_set_option مقدار XML_OPTION_CASE_FOLDING را برابر صفر قرار می‌دهیم تا حالت حروف (case) نام تگ‌ها حفظ شود. سپس callbackهای شروع و پایان تگ تعریف شده و xml_parse فراخوانی می‌شود. بدون این گزینه، نام تگ “Child” در callbackها به “CHILD” تبدیل می‌شد.

مثال عملی 2 — تبدیل خروجی به UTF-8

<?php
// فرض کنیم ورودی با ISO-8859-1 باشد
$xml = "<?xml version='1.0' encoding='ISO-8859-1'?>n<root><item>olá</item></root>";

$parser = xml_parser_create("ISO-8859-1");
// تعیین اینکه رشته‌هایی که به callback می‌رسند به UTF-8 تبدیل شوند
xml_parser_set_option($parser, XML_OPTION_TARGET_ENCODING, "UTF-8");

xml_set_element_handler($parser,
    function($p, $name, $attrs){ echo "Start: $namen"; },
    function($p, $name){ echo "End: $namen"; }
);

if (!xml_parse($parser, $xml, true)) {
    printf("Error: %sn", xml_error_string(xml_get_error_code($parser)));
}
xml_parser_free($parser);
?>

توضیح: این مثال نشان می‌دهد چگونه می‌توان خروجی callbackها را به UTF-8 تبدیل کرد. هنگام پردازش فایل‌هایی که با رمزگذاری‌های متفاوت هستند، تنظیم XML_OPTION_TARGET_ENCODING مفید است تا داده‌ها در برنامه شما همگی در یک encoding واحد (معمولاً UTF-8) دریافت شوند.

نکات حرفه‌ای و بهترین شیوه‌ها

اگر می‌خواهید نام تگ‌ها را دقیقاً مطابق XML ورودی ببینید (مثلاً در زمانی که case مهم است)، XML_OPTION_CASE_FOLDING را خاموش کنید.
برای برنامه‌های بین‌المللی و جلوگیری از مشکلات کاراکتری، خروجی callbackها را به UTF-8 تبدیل کنید.
پس از پایان کار با تجزیه‌گر حتماً xml_parser_free() را فراخوانی کنید تا منابع آزاد شوند.
در پردازش اسناد بسیار بزرگ یا نیاز به کار با درخت XML کامل، بهتر است به جای SAX از DOM یا XMLReader استفاده کنید؛ SAX برای پردازش خطی و جریان‌های بزرگ مناسب است.
برای دیباگ خطاهای XML از توابع xml_error_string و xml_get_current_line_number استفاده کنید تا پیام خطا و محل آن را بیابید.

اشکال‌زدایی و محدودیت‌ها

اگر تجزیه‌گر خطا می‌دهد، همیشه مقدار بازگشتی xml_parse را بررسی کنید و از xml_get_error_code و xml_error_string برای نمایش پیام مناسب استفاده کنید. همچنین توجه داشته باشید که تغییر برخی گزینه‌ها پس از شروع parse (مثلاً در میانه فراخوانی xml_parse با داده‌های بخش‌بخش) ممکن است رفتار نامطلوبی ایجاد کند؛ بهتر است گزینه‌ها را قبل از شروع parse تنظیم کنید.

خلاصه و جمع‌بندی

xml_parser_set_option() تابعی ساده اما قدرتمند برای کنترل رفتار SAX parser در PHP است. با استفاده از این تابع می‌توانید نحوه نمایش نام تگ‌ها و رمزگذاری خروجی را مدیریت کنید، که برای سازگاری داده‌ها و جلوگیری از خطاهای کاراکتری حیاتی است. برای استفاده ایمن و قابل نگهداری، گزینه‌ها را پیش از شروع parse تنظیم کرده و خطاها را به‌درستی مدیریت کنید. در صورتی که نیاز به پردازش ساختاری کامل یا کار با XMLهای غول‌آسا دارید، ابزارهای مبتنی بر DOM یا XMLReader ممکن است گزینه‌های بهتری باشند.

آیا این مطلب برای شما مفید بود ؟

خیر

بله