تابع xml_set_element_handler() در PHP

تابع xml_set_element_handler() در PHP یکی از ابزارهای اصلی برای پردازش رویدادمحور فایل‌های XML است. این تابع بخشی از API مبتنی بر Expat (SAX-like) است و به شما اجازه می‌دهد تا برای شروع و پایان هر عنصر (element) در XML، callback تعریف کنید. این روش برای پردازش جریان‌های بزرگ XML یا زمانی که نمی‌خواهید کل سند را در حافظه بارگذاری کنید، بسیار مناسب است.

چرا از xml_set_element_handler استفاده کنیم؟

• پردازش کم‌حافظه‌ای (streaming): مناسب برای فایل‌های بزرگ.
• انعطاف‌پذیری بالا: قادر به تعریف منطق اختصاصی برای هر عنصر.
• عملکرد بهتر نسبت به بارگذاری کامل DOM در موارد خاص.

اصول کار

فرایند کلی به صورت زیر است:

• ایجاد یک XML parser با xml_parser_create().
• ثبت توابع callback برای شروع و پایان عناصر با xml_set_element_handler().
• ثبت (اختیاری) توابع دیگر مانند xml_set_character_data_handler() برای متن عناصر.
• خواندن داده‌ها (مثلاً از فایل) و ارسال آن‌ها به xml_parse() به صورت قطعات.
• آزادسازی منابع با xml_parser_free().

امضای تابع

پارامترهایی که callbackها دریافت می‌کنند

• تابع شروع (start): دو پارامتر — نام عنصر (string) و آرایه‌ای از attributes (associative array).
• تابع پایان (end): یک پارامتر — نام عنصر (string).
• نکته مهم: متن درون عناصر توسط xml_set_character_data_handler() مدیریت می‌شود و ممکن است در چند فراخوانی تجزیه شود؛ بنابراین باید آن را تجمعی ذخیره کنید.

مثال پایه‌ای — تجزیه ساده از فایل XML

<?php
$parser = xml_parser_create();

// متغیرهای ذخیره وضعیت
$currentElement = null;
$textBuffer = '';

// تابع شروع عنصر
function startElement($parser, $name, $attrs) {
    global $currentElement, $textBuffer;
    $currentElement = $name;
    $textBuffer = '';
    echo "Start: $namen";
    if (!empty($attrs)) {
        echo "Attributes:n";
        foreach ($attrs as $k => $v) {
            echo "  $k = $vn";
        }
    }
}

// تابع پایان عنصر
function endElement($parser, $name) {
    global $currentElement, $textBuffer;
    $trimmed = trim($textBuffer);
    if ($trimmed !== '') {
        echo "Text for $name: $trimmedn";
    }
    echo "End: $namen";
    $currentElement = null;
    $textBuffer = '';
}

// تابع متن عناصر
function characterData($parser, $data) {
    global $textBuffer;
    $textBuffer .= $data;
}

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

$fp = fopen("sample.xml", "r");
while (!feof($fp)) {
    $data = fread($fp, 4096);
    if (!xml_parse($parser, $data, feof($fp))) {
        die(sprintf("XML error: %s at line %d",
            xml_error_string(xml_get_error_code($parser)),
            xml_get_current_line_number($parser)));
    }
}
fclose($fp);
xml_parser_free($parser);
?>

توضیح: این کد یک parser ایجاد می‌کند، توابع شروع/پایان/متن را ثبت می‌کند و سپس فایل sample.xml را به صورت قطعه‌ای می‌خواند و به parser ارسال می‌کند. متن داخلی عناصر در $textBuffer تجمعی نگه داشته می‌شود زیرا handler متن ممکن است چند بار فراخوانی شود.

نمونه حرفه‌ای‌تر: استفاده از کلاس برای مدیریت وضعیت

<?php
class MyXMLHandler {
    private $current = [];
    private $buffer = '';

    public function start($parser, $name, $attrs) {
        $this->buffer = '';
        // ذخیره برخی اطلاعات در پشته برای ساختار درختی
        $this->current[] = ['name'=>$name, 'attrs'=>$attrs, 'text'=>''];
    }

    public function end($parser, $name) {
        $node = array_pop($this->current);
        $node['text'] = trim($this->buffer);
        // اینجا می‌توانید node را به دیتابیس بفرستید یا ساختار را اصلاح کنید
        // مثال: چاپ ساده
        echo "Element: {$node['name']} - Text: {$node['text']}n";
        $this->buffer = '';
    }

    public function char($parser, $data) {
        $this->buffer .= $data;
    }
}

$handler = new MyXMLHandler();
$parser = xml_parser_create();
xml_set_element_handler($parser, array($handler, "start"), array($handler, "end"));
xml_set_character_data_handler($parser, array($handler, "char"));

// parse file as before...
xml_parser_free($parser);
?>

توضیح: در این مثال با استفاده از یک شیء، وضعیت مربوط به پشته عناصر و بافر متن را نگه می‌داریم که ساختار خواناتر و منعطف‌تری فراهم می‌کند. همچنین این روش مناسب مدیریت خطا و نگهداری وضعیت برای پردازش پیچیده‌تر است.

نکات عملی و بهینه‌سازی

• برای غیرفعال یا فعال‌سازی تبدیل حروف کوچک/بزرگ خودکار از xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0) استفاده کنید.
• همیشه در پایان xml_parser_free() را فراخوانی کنید تا منابع آزاد شوند.
• اگر با فایل‌های بزرگ سروکار دارید، از خواندن قطعه‌ای (chunked) و xml_parse() در حلقه استفاده کنید تا از مصرف زیاد حافظه جلوگیری کنید.
• به یاد داشته باشید که attributeها در تابع شروع به صورت آرایه‌ای پاس داده می‌شوند — ممکن است نیاز به نرمال‌سازی یا بررسی داشته باشند.
• برای دیباگ از xml_get_error_code() و xml_error_string() استفاده کنید تا محل خطا را تشخیص دهید.

موارد کاربردی (Use Cases)

• پردازش لاگ‌ها یا دیتای حجیم صادرشده به صورت XML.
• ایندکس‌سازی و استخراج فیلدها برای واردسازی به پایگاه‌داده.
• تبدیل XML به ساختارهای خطی یا ارسال رویدادی در زمان واقعی.

نتیجه‌گیری

تابع xml_set_element_handler() یک ابزار قدرتمند برای پردازش رویدادمحور XML در PHP است. اگر با فایل‌های بزرگ یا جریان‌های XML سروکار دارید که نمی‌خواهید کل سند را در حافظه بارگذاری کنید، استفاده از این رویکرد (SAX-like) پیشنهاد می‌شود. با تلفیق آن با xml_set_character_data_handler() و مدیریت مناسب بافر متن و خطاها، می‌توانید پردازش قابل‌اطمینان و کارآمدی داشته باشید.

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

ارسال