View source

{{toc | category = Вспомогательные классы | sortkey = 002.001}}
<!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! -->
<code>XML</code> - удобный формат описания данных, который строится по древовидной структуре. Каждый элемент может содержать значение и/или другие элементы. Текст внутри элемента может чередоваться с дочерними элементами, но он всё равно будет расценен как единое значение. Кроме того, у каждого элемента могут быть заданы атрибуты. Всё выше описанное отражено в ниже приведённом примере (пусть это будет файл "<code>sample.xml</code>"):
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<our_document>
	<some_tag>
		Some tag's content.
	</some_tag>
	<planet_earth>
	    <continent id="1">
		North America
            	<country id="1">
			Canada
		</country>
          	<country id="2">
			USA
		</country>
	    </continent>
	    <continent id="2">
	    	Europe
            	<country id="1">
			Estonia
		</country>
            	<country id="2">
			Latvia
		</country>
            	<country id="3">
			Lithuania
		</country>
	    </continent>
	</planet_earth>
</our_document>
</source>

== Блок CDATA ==
Если требуется указать в качестве содержания одного из элементов символы, которые могут помешать корректной разборке XML документа, то нужно содержание элемента заключать в блок CDATA. К ряду символов таких символов относятся символы "<code>></code>", "<code><</code>" и "<code>&</code>". Синтаксис блока <code>CDATA</code> выглядит следующим образом:

<source lang="xml">
<![CDATA[Some symbolic data, that > breaks & xml]]>
</source>

Данные внутри блока <code>CDATA</code> не должны содержать последовательность "<code>]]></code>", т.к. она будет воспринята как окончание данного блока. Если задание такой последовательности символов необходимо, следует воспользоваться следующим подходом:

<source lang="xml">
<![CDATA[]]]]><![CDATA[>]]>
</source>

В выше приведённом примере данные разбиты на два фрагмента и каждый из них заключён в свой блок <code>CDATA</code>. Особенно удобно применение <code>CDATA</code> в случае, когда нужно написать <code>XML</code>, который будет показан пользователю, но не обработан при разборке XML документа.

== Получение XML документа ==
Перед тем, как разбирать <code>XML</code> документ, содержащийся в файле, его нужно сначала прочитать.

=== Получение локального файла ===
Для получения локального файла (т.е. находящегося на том-же компьютере, что и сам сайт) следует использовать стандартную функцию [http://php.prod.intechnic.lv/manual/en/function.file-get-contents.php file_get_contents]. Данная функция возвращает содержание файла, путь к которому передан в качестве первого её аргумента.

<source lang="php">
$file_contents = file_get_contents(WRITEABLE . '/user_files/sample.xml');
</source>

=== Получение удалённого файла ===
Функция [http://php.prod.intechnic.lv/manual/en/function.file-get-contents.php file_get_contents] также позволяет получать содержимое файлов, находящихся на удалённых ресурсах. Однако, в целях безопасности, на сервере может быть запрещена эта возможность. Поэтому настоятельно рекомендуется получать удалённый файл при помощи стандартного класса K4 - <code>kCurlHelper</code>.

<source lang="php">
$curl_helper =& $this->Application->recallObject('CurlHelper');
/* @var $curl_helper kCurlHelper */

$xml_data = $curl_helper->Send('http://sample-host.com/sample.xml');
</source>

У метода <code>Send</code> также есть второй необязательный параметр, который указывает на то, что нужно закрывать соединение сразу после получения содержания документа. По умолчанию он равен "<code>true</code>", т.е. закрывать соединение.

== Разборка XML документа ==
В классе <code>kXMLHelper</code> реализован удобный механизм разбора XML документа. Сначала следует создать экземпляр класса.

<source lang="php">
$xml_helper =& $this->Application->recallObject('kXMLHelper');
/* @var $xml_helper kXMLHelper */
</source>

Далее, начать обработку полученного ранее XML документа.

<source lang="php">
$root_node =& $xml_helper->Parse($file_contents);
</source>

В результате будет возвращена древовидная структура объектов, в которой все объекты связаны при помощи ссылок. Содержимое каждого объекта класса <code>kXMLNode</code> выглядит так:

<source lang="php">
kxmlnode Object (
	[Name] => xml_element_name
	[Attributes] => Array
	(
		[1st_attribute_name] => 1st_attribute_value
		[2nd_attribute_name] => 2nd_attribute_value
		...
	)
	[Children] => Array
	(
		[0] =>	kxmlnode Object
		[1] =>	kxmlnode Object
		...
	)
	[Data] => text_value_that_this_XML_element_encapsulates
	[firstChild] => kxmlnode Object
	[lastChild] => kxmlnode Object
	[Parent] =>  kxmlnode Object
	[Position] => 1
)
</source>

{{TipBox|Всё ниже приведённое описание содержания объекта класса kXMLNode будет основано на примере, приведённом в начале статьи.}}
Переменной <code>$root_node</code> будет присвоен родительский (root) объект, т.е. это объект xml-элемента "<code>our_document</code>". Атрибут "<code>Children</code>" (private) содержит массив всех дочерних элементов текущего элемента. В данном примере ими являются два элемента - "<code>some_tag</code>" и "<code>planet_earth</code>". У последнего - два дочерних элемента "<code>continent</code>". Важно понимать, что элементы массива - точно такие же объекты, как и текущий. У них, в свою очередь, могут быть свои дочерние элементы, и так далее.

У каждого элемента есть атрибут <code>Position</code>. Это - порядковый номер элемента среди соседних элементов (элементов того же уровня, например - "country" Canada и "country" USA). Атрибуты "<code>firstChild</code>" и "<code>lastChild</code>" содержат первый и последний (с точки зрения его <code>Position</code>) дочерний элемент соответственно.

Для последующей обработки полученной информации используется методы и атрибуты именно класса <code>kXMLNode</code>.

== Практическое использование kXMLHelper ==
Ниже приведён код, который распечатает все страны описанного выше XML-документа.

<source lang="php">
$root_node =& $xml_helper->Parse($xml_data);
/* @var $root_node kXMLNode */

// Getting first continent node
$continent_node =& $root_node->FindChild('continent');

// Cycling through it and all the rest continent nodes
do {
	// Getting first country node
	$country_node =& $continent_node->firstChild;

	// Cycling through it and all the rest continent nodes
    	do {
        	echo $continent_node->Attributes['ID'] . ' - ' . trim($continent_node->Data) . ': ' . $country_node->Attributes['ID'] . ' - ' . trim($country_node->Data) . '<br/>';
    	} while ($country_node =& $country_node->NextSibling());
} while ($continent_node =& $continent_node->NextSibling());
</source>

В переменной <code>$continent_node</code> сохраняется первый найденный объект "<code>continent</code>", т.е. - "<code>North America</code>". В первом цикле перебираются континенты. Для перехода к элементу того же уровня используется метод <code>NextSibling</code> (есть противоположный ему метод <code>PrevSibling</code>). Из континента выбирается первая страна. Внутренний цикл перебирает все страны данного континента и делает вывод в приведённом ниже формате. Как можно заметить, текстовое значение элементов доступно через атрибут "<code>Data</code>". 

 1 - North America: 1 - Canada
 1 - North America: 2 - USA
 2 - Europe: 1 - Estonia
 2 - Europe: 2 - Latvia
 2 - Europe: 3 - Lithuania

== Методы класса "kXMLNode" ==
Ниже приведены public методы класса <code>kXMLNode</code>. Все методы рассчитаны на чтение данных, но не на их запись.

{| class="prettytable" 
! метод || описание
|-
| <code>&FindChild($name)</code>
| Возвращает первый встретившийся элемент-потомок с указанным именем. Работает рекурсивно, до самого последнего уровня.
|-
| <code>FindChildValue($name, $attr=null)</code>
| Возвращает либо значение элемента-потомка (если задано только его имя), либо один из атрибутов (если явно указан).
|-
| <code>&GetChildByPosition($position)</code>
| Возвращает дочерний элемент, который находится по указанной позиции.
|-
| <code>GetXML()</code>
| Генерирует и возвращает XML-документ, построенный от текущего элемента. Актуально при предыдущем изменении структуры и не только.
|}