xml wrangler
v1.3.0
XML Wrangler - это упрощенная библиотека PHP, предназначенная для упрощения чтения и написания XML. XML Wrangler был построен с учетом опыта разработчика - вы можете прочитать любой тип XML -файла, даже с сложными пространствами имен и даже большими файлами XML. Это также вызовет исключения, если XML недействителен!
XML Wrangler установлен через композитор.
composer require saloonphp/xml-wrangler
Требуется PHP 8.1+
Чтение XML может быть выполнено путем передачи строки XML или файла в считыватель XML и используя один из множества методов для поиска и поиска конкретного элемента или значения. Вы также можете преобразовать каждый элемент в легко проверенный массив, если вы предпочитаете. Если вам нужно получить доступ к атрибутам на элементе, вы можете использовать Element DTO, который является простым классом для доступа к контенту и атрибутам. XML Wrangler предоставляет методы для итерации через несколько элементов, сохраняя только один элемент в памяти за раз.
< breakfast_menu >
< food soldOut = " false " bestSeller = " true " >
< name >Belgian Waffles</ name >
< price >$5.95</ price >
< description >Two of our famous Belgian Waffles with plenty of real maple syrup</ description >
< calories >650</ calories >
</ food >
< food soldOut = " false " bestSeller = " false " >
< name >Strawberry Belgian Waffles</ name >
< price >$7.95</ price >
< description >Light Belgian waffles covered with strawberries and whipped cream</ description >
< calories >900</ calories >
</ food >
< food soldOut = " false " bestSeller = " true " >
< name >Berry-Berry Belgian Waffles</ name >
< price >$8.95</ price >
< description >Light Belgian waffles covered with an assortment of fresh berries and whipped cream</ description >
< calories >900</ calories >
</ food >
</ breakfast_menu > <?php
use Saloon XmlWrangler XmlReader ;
$ reader = XmlReader :: fromString ( $ xml );
// Retrieve all values as one simple array
$ reader -> values (); // ['breakfast_menu' => [['name' => '...'], ['name' => '...'], ['name' => '...']]
// Use dot-notation to find a specific element
$ reader -> value ( ' food.0 ' )-> sole (); // ['name' => 'Belgian Waffles', 'price' => '$5.95', ...]
// Use the element method to get a simple Element DTO containing attributes and content
$ reader -> element ( ' food.0 ' )-> sole (); // Element::class
// Use XPath to query the XML
$ reader -> xpathValue ( ' //food[@bestSeller="true"]/name ' )-> get (); // ['Belgian Waffles', 'Berry-Berry Belgian Waffles']
// Use getAttributes() to get the attributes on the elements
$ reader -> element ( ' food.0 ' )-> sole ()-> getAttributes (); // ['soldOut' => false, 'bestSeller' => true]
// Use getContent() to get the contents of the elements
$ reader -> element ( ' food.0 ' )-> sole ()-> getContent (); // ['name' => 'Belgian Waffles', 'price' => '$5.95', ...] Написание XML так же просто, как определение массива PHP и использование ключей и значений для определения элементов. Когда вам нужно определить элементы с несколькими характеристиками, такими как атрибуты или пространства имен, вы можете использовать DTO Element для определения более продвинутых элементов.
<?php
use Saloon XmlWrangler Data Element ;
use Saloon XmlWrangler XmlWriter ;
$ writer = new XmlWriter ;
$ xml = $ writer -> write ( ' breakfast_menu ' , [
' food ' => [
[
' name ' => ' Belgian Waffles ' ,
' price ' => ' $5.95 ' ,
' description ' => ' Two of our famous Belgian Waffles with plenty of real maple syrup ' ,
' calories ' => ' 650 ' ,
],
[
' name ' => ' Strawberry Belgian Waffles ' ,
' price ' => ' $7.95 ' ,
' description ' => ' Light Belgian waffles covered with strawberries and whipped cream ' ,
' calories ' => ' 900 ' ,
],
// You can also use the Element class if you need to define elements with
// namespaces or with attributes.
Element :: make ([
' name ' => ' Berry-Berry Belgian Waffles ' ,
' price ' => ' $8.95 ' ,
' description ' => ' Light Belgian waffles covered with an assortment of fresh berries and whipped cream ' ,
' calories ' => ' 900 ' ,
])-> setAttributes ([ ' bestSeller ' => ' true ' ]),
],
]);Приведенный выше код создаст следующий XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< breakfast_menu >
< food >
< name >Belgian Waffles</ name >
< price >$5.95</ price >
< description >Two of our famous Belgian Waffles with plenty of real maple syrup</ description >
< calories >650</ calories >
</ food >
< food >
< name >Strawberry Belgian Waffles</ name >
< price >$7.95</ price >
< description >Light Belgian waffles covered with strawberries and whipped cream</ description >
< calories >900</ calories >
</ food >
< food bestSeller = " true " >
< name >Berry-Berry Belgian Waffles</ name >
< price >$8.95</ price >
< description >Light Belgian waffles covered with an assortment of fresh berries and whipped cream</ description >
< calories >900</ calories >
</ food >
</ breakfast_menu >Этот раздел в документации предназначен для использования читателя XML.
Читатель XML может принять различные типы вводов. Вы можете использовать строку XML, файл или предоставить ресурс. Вы также можете прочитать XML непосредственно из ответа PSR (например, от Guzzle) или ответа салона.
use Saloon XmlWrangler XmlReader ;
$ reader = XmlReader :: fromString ( ' <?xml version="1.0" encoding="utf-8"?><breakfast_menu>... ' );
$ reader = XmlReader :: fromFile ( ' path/to/file.xml ' );
$ reader = XmlReader :: fromStream ( fopen ( ' path/to/file.xml ' , ' rb ' );
$ reader = XmlReader :: fromPsrResponse ( $ response );
$ reader = XmlReader :: fromSaloonResponse ( $ response );Предупреждение из -за ограничений базового класса PHP XmlReader, методов
fromStream,fromPsrResponseиfromSaloonсоздаст временный файл на вашем компьютере/сервере для чтения, с которого будет автоматически удалено, когда читатель будет разрушен. Вам нужно будет убедиться, что у вас достаточно хранения на вашем компьютере, чтобы использовать этот метод.
Вы можете использовать методы elements и values для преобразования всего документа XML в массив. Если вы хотите массив значений, используйте метод values - но если вам нужно получить доступ к атрибутам на элементах, метод elements вернет массив Element DTO.
$ reader = XmlReader :: fromString (...);
$ elements = $ reader -> elements (); // Array of `Element::class` DTOs
$ values = $ reader -> values (); // Array of values.Примечание, если вы читаете большой XML -файл, вместо этого вы должны использовать
elementили методыvalue. Эти методы могут переиграть через большие XML -файлы без запуска памяти.
Вы можете использовать метод value , чтобы получить значение определенного элемента. Вы можете использовать точечную ноцию для поиска детских элементов. Вы также можете использовать целые числа, чтобы найти конкретные позиции нескольких элементов. Этот метод ищет весь корпус XML эффективным образом.
Этот метод вернет класс LazyQuery , который имеет разные методы для извлечения данных.
$ reader = XmlReader :: fromString ( '
<?xml version="1.0" encoding="utf-8"?>
<person>
<name>Sammyjo20</name>
<favourite-songs>
<song>Luke Combs - When It Rains It Pours</song>
<song>Sam Ryder - SPACE MAN</song>
<song>London Symfony Orchestra - Starfield Suite</song>
</favourite-songs>
</person>
' );
$ reader -> value ( ' person.name ' )-> sole () // ' Sammyjo20 '
$ reader -> value ( ' song ' )-> get (); // ['Luke Combs - When It Rains It Pours', 'Sam Ryder - SPACE MAN', ...]
$ reader -> value ( ' song.2 ' )-> sole (); // 'London Symfony Orchestra - Starfield Suite' Вы можете использовать метод element для поиска определенного элемента. Этот метод предоставит класс Element , который содержит значение и атрибуты. Вы можете использовать точечную ноцию для поиска детских элементов. Вы также можете использовать целые числа, чтобы найти конкретные позиции нескольких элементов. Этот метод ищет все тело XML эффективным образом.
Этот метод вернет класс LazyQuery , который имеет разные методы для извлечения данных.
$ reader = XmlReader :: fromString ( '
<?xml version="1.0" encoding="utf-8"?>
<person>
<name>Sammyjo20</name>
<favourite-songs>
<song>Luke Combs - When It Rains It Pours</song>
<song>Sam Ryder - SPACE MAN</song>
<song>London Symfony Orchestra - Starfield Suite</song>
</favourite-songs>
</person>
' );
$ reader -> element ( ' name ' )-> sole (); // Element('Sammyjo20')
$ reader -> element ( ' song ' )-> get (); // [Element('Luke Combs - When It Rains It Pours'), Element('Sam Ryder - SPACE MAN'), ...]
$ reader -> element ( ' song.2 ' )-> sole (); // Element('London Symfony Orchestra - Starfield Suite') Иногда легче пересечь документ XML, когда вам не нужно беспокоиться о пространствах имен и префиксах к элементам. Если вы хотите удалить их, вы можете использовать метод removeNamespaces() на читателе.
$ reader = XmlReader :: fromString (...);
$ reader -> removeNamespaces (); При поиске большого файла вы можете использовать lazy или collectLazy методы, которые вернет генератор результатов, сохраняя только один элемент в памяти за раз.
$ names = $ reader -> element ( ' name ' )-> lazy ();
foreach ( $ names as $ name ) {
//
} Если вы используете Laravel, вы можете использовать методы collect и collectLazy , которые преобразуют элементы в коллекцию Laravel/Lazy. Если вы не используете Laravel, вы можете установить пакет illuminate/collections через композитор, чтобы добавить эту функциональность.
$ names = $ reader -> value ( ' name ' )-> collect ();
$ names = $ reader -> value ( ' name ' )-> collectLazy (); Иногда вы можете искать определенный элемент или значение, где элемент содержит конкретный атрибут. Вы можете сделать это, предоставив второй аргумент для метода value или element . Это будет искать последний элемент для атрибутов и вернется, если они соответствуют.
$ reader = XmlReader :: fromString ( '
<?xml version="1.0" encoding="utf-8"?>
<person>
<name>Sammyjo20</name>
<favourite-songs>
<song>Luke Combs - When It Rains It Pours</song>
<song>Sam Ryder - SPACE MAN</song>
<song recent="true">London Symfony Orchestra - Starfield Suite</song>
</favourite-songs>
</person>
' );
$ reader -> element ( ' song ' , [ ' recent ' => ' true ' ])-> sole (); // Element('London Symfony Orchestra - Starfield Suite')
$ reader -> value ( ' song ' , [ ' recent ' => ' true ' ])-> sole (); // 'London Symfony Orchestra - Starfield Suite'XPath - это фантастический способ поиска через XML. С помощью одной строки вы можете искать конкретный элемент с конкретными атрибутами или индексами. Если вы заинтересованы в изучении XPath, вы можете нажать здесь для полезного чистого листа.
Вы можете использовать метод xpathValue , чтобы найти значение конкретного элемента с помощью запроса XPath. Этот метод вернет класс Query , который имеет разные методы для извлечения данных.
<?php
$ reader = XmlReader :: fromString (...);
$ reader -> xpathValue ( ' //person/favourite-songs/song[3] ' )-> sole (); // 'London Symfony Orchestra - Starfield Suite' Вы можете использовать метод xpathElement , чтобы найти конкретный элемент с запросом XPath. Этот метод вернет класс Query , который имеет разные методы для извлечения данных.
<?php
$ reader = XmlReader :: fromString (...);
$ reader -> xpathElement ( ' //person/favourite-songs/song[3] ' )-> sole (); // Element('London Symfony Orchestra - Starfield Suite')Предупреждение из -за ограничений с помощью XPath - вышеуказанные методы, используемые для запроса с XPath, не являются безопасными памятью и не могут быть подходящими для больших документов XML.
Вы могли бы оказаться с XML -документом, который содержит невыполненный атрибут xmlns - например, это:
< container xmlns = " http://example.com/xml-wrangler/person " xmlns : xsi = " http://www.w3.org/2001/XMLSchema-instance " /> Когда это произойдет, XML Wrangler автоматически удаляет эти незаполненные пространства имен для повышения совместимости. Если вы хотите сохранить эти пространства имен, вы можете использовать setXpathNamespaceMap для картирования каждого не подлежащего пространству имен XML.
$ reader = XmlReader :: fromString (...);
$ reader -> setXpathNamespaceMap ([
' root ' => ' http://example.com/xml-wrangler/person ' ,
]);
$ reader -> xpathValue ( ' //root:person/root:favourite-songs/root:song[3] ' )-> sole ();Этот раздел в документации предназначен для использования писателя XML.
Самое основное использование считывателя - использовать струнные клавиши для имен элементов и значений для значений элемента. Автор принимает бесконечно вложенные массивы для вложенных элементов.
use Saloon XmlWrangler XmlWriter ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [
' name ' => ' Sam ' ,
' twitter ' => ' @carre_sam ' ,
' facts ' => [
' favourite-song ' => ' Luke Combs - When It Rains It Pours '
],
]);Приведенный выше код будет преобразован в следующий XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< root >
< name >Sam</ name >
< twitter >@carre_sam</ twitter >
< facts >
< favourite-song >Luke Combs - When It Rains It Pours</ favourite-song >
</ facts >
</ root > При написании XML вам часто нужно определять атрибуты и пространства имен на ваших элементах. Вы можете использовать класс Element в массиве XML, чтобы добавить элемент с атрибутом или пространством имен. Вы можете смешать класс Element с другими массивами и значениями строки.
use Saloon XmlWrangler XmlWriter ;
use Saloon XmlWrangler Data Element ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [
' name ' => ' Sam ' ,
' twitter ' => Element :: make ( ' @carre_sam ' )-> addAttribute ( ' url ' , ' https://twitter.com/@carre_sam ' ),
' facts ' => [
' favourite-song ' => ' Luke Combs - When It Rains It Pours '
],
' soap:custom-namespace ' => Element :: make ()-> addNamespace ( ' soap ' , ' http://www.w3.org/2003/05/soap-envelope ' ),
]);Это приведет к следующему XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< root >
< name >Sam</ name >
< twitter url = " https://twitter.com/@carre_sam " >@carre_sam</ twitter >
< facts >
< favourite-song >Luke Combs - When It Rains It Pours</ favourite-song >
</ facts >
< soap : custom-namespace xmlns : soap = " http://www.w3.org/2003/05/soap-envelope " />
</ root >Вам часто нужно определить множество элементов. Вы можете сделать это, просто предоставив множество значений или классов элементов.
use Saloon XmlWrangler XmlWriter ;
use Saloon XmlWrangler Data Element ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [
' name ' => ' Luke Combs ' ,
' songs ' => [
' song ' => [
' Fast Car ' ,
' The Kind Of Love We Make ' ,
' Beautiful Crazy ' ,
Element :: make ( ' She Got The Best Of Me ' )-> addAttribute ( ' hit ' , ' true ' ),
],
],
]);Это приведет к следующему XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< root >
< name >Luke Combs</ name >
< songs >
< song >Fast Car</ song >
< song >The Kind Of Love We Make</ song >
< song >Beautiful Crazy</ song >
< song hit = " true " >She Got The Best Of Me</ song >
</ songs >
</ root > Иногда вам может потребоваться изменить имя корневого элемента. Это можно настроить как первый аргумент метода write .
$ xml = XmlWriter :: make ()-> write ( ' custom-root ' , [...]) Если вы хотите добавить атрибуты и пространства имен в корневой элемент, вы также можете использовать здесь класс RootElement .
use Saloon XmlWrangler Data RootElement ;
$ rootElement = RootElement :: make ( ' root ' )-> addNamespace ( ' soap ' , ' http://www.w3.org/2003/05/soap-envelope ' );
$ xml = XmlWriter :: make ()-> write ( $ rootElement , [...]) Если вам нужно добавить тег CDATA, вы можете использовать класс CDATA .
use Saloon XmlWrangler Data CDATA ; use Saloon XmlWrangler XmlWriter ;
use Saloon XmlWrangler Data Element ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [
' name ' => ' Sam ' ,
' custom ' => CDATA :: make ( ' Here is some CDATA content! ' ),
]);Это приведет к следующему XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< root >
< name >Sam</ name >
< custom > <![CDATA[ Here is some CDATA content! ]]> </ custom >
</ root > Иногда у вас может быть часть XML, которую вы будете использовать по нескольким запросам XML в вашем приложении. С помощью XML Wrangler вы можете создать «композируемые» элементы, где вы можете определить свой контент XML в классе, который вы можете повторно использовать в своем приложении. Расширить класс Element и использовать метод защищенного статического compose .
<?php
use Saloon XmlWrangler XmlWriter ;
use Saloon XmlWrangler Data Element ;
class BelgianWafflesElement extends Element
{
protected function compose (): void
{
$ this
-> setAttributes ([
' soldOut ' => ' false ' ,
' bestSeller ' => ' true ' ,
])
-> setContent ([
' name ' => ' Belgian Waffles ' ,
' price ' => ' $5.95 ' ,
' description ' => ' Two of our famous Belgian Waffles with plenty of real maple syrup ' ,
' calories ' => ' 650 ' ,
]);
}
}
$ writer = XmlWriter :: make ()-> write ( ' root ' , [
' food ' => new BelgianWafflesElement ,
]);Это приведет к тому, что XML будет так:
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< breakfast_menu >
< food soldOut = " false " bestSeller = " true " >
< name >Belgian Waffles</ name >
< price >$5.95</ price >
< description >Two of our famous Belgian Waffles with plenty of real maple syrup</ description >
< calories >650</ calories >
</ food >
</ breakfast_menu > Кодирование XML по умолчанию- utf-8 , версия XML по умолчанию- 1.0 , а автономный по умолчанию null (анализаторы XML не интерпретируют автономный атрибут так же, как и false ). Если вы хотите настроить это, вы можете с помощью методов setXmlEncoding , setXmlVersion и setXmlStandalone на авторе.
use Saloon XmlWrangler XmlWriter ;
$ writer = new XmlWriter ();
$ writer -> setXmlEncoding ( ' ISO-8859-1 ' );
$ writer -> setXmlVersion ( ' 2.0 ' );
$ writer -> setXmlStandalone ( true );
// $writer->write(...); Что приводит к декларации XML <?xml version="2.0" encoding="ISO-8859-1" standalone="yes"?> .
Вы можете добавить пользовательскую «инструкцию по обработке» в XML, используя метод addProcessingInstruction .
use Saloon XmlWrangler XmlWriter ;
$ writer = new XmlWriter ();
$ writer -> addProcessingInstruction ( ' xml-stylesheet ' , ' type="text/xsl" href="base.xsl" ' );
$ xml = $ writer -> write ( ' root ' , [ ' name ' => ' Sam ' ]);Это приведет к следующему XML
<? xml version = " 1.0 " encoding = " utf-8 " ?>
<? xml-stylesheet type = " text/xsl " href = " base.xsl " ?>
< root >
< name >Sam</ name >
</ root > По умолчанию написание XML не является министерством. Вы можете предоставить третий аргумент методу write для министерства XML.
use Saloon XmlWrangler XmlWriter ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [...], minified: true );XML Wrangler - это простая обертка вокруг двух действительно мощных библиотек, которые делают много работы. Обе библиотеки фантастические и заслуживают звезды!
