xml wrangler
v1.3.0
XML Wranglerは、XMLの読み書きを簡単にするために設計された単純なPHPライブラリです。 XML Wranglerは、開発者のエクスペリエンスを念頭に置いて構築されています。複雑な名前空間や大きなXMLファイルであっても、あらゆるタイプのXMLファイルを読むことができます。また、XMLが無効である場合、例外をスローします！
XMLラングラーはComposerを介してインストールされます。
composer require saloonphp/xml-wrangler
PHP 8.1+が必要です
XMLの読み取りは、XML文字列またはファイルをXMLリーダーに渡し、多くの方法のいずれかを使用して特定の要素または値を検索して見つけることで実行できます。必要に応じて、すべての要素を簡単に横断可能な配列に変換することもできます。要素上の属性にアクセスする必要がある場合は、コンテンツと属性にアクセスするための単純なクラスであるElement DTOを使用できます。 XML Wranglerは、一度に1つの要素のみをメモリに保持しながら、複数の要素を繰り返す方法を提供します。
< 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アレイを定義し、キーと値を使用して要素を定義するのと同じくらい簡単です。属性や名前空間などのいくつかの特性を持つ要素を定義する必要がある場合、 Element DTOを使用して、より高度な要素を定義できます。
<?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文字列、ファイル、またはリソースを提供することもできます。また、PSR応答（Guzzleから）またはサルーン応答からXMLを直接読み取ることもできます。
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 ();大きなファイルを検索するときは、一度に1つのアイテムのみをメモリに保持する結果のジェネレーターを返すlazyまたはcollectLazyメソッドを使用できます。
$ names = $ reader -> element ( ' name ' )-> lazy ();
foreach ( $ names as $ name ) {
//
}Laravelを使用している場合は、要素をLaravelコレクション/レイジーコレクションに変換するcollectとcollectLazyメソッドを使用できます。 Laravelを使用していない場合は、Composerを介してilluminate/collectionsパッケージをインストールして、この機能を追加できます。
$ names = $ reader -> value ( ' name ' )-> collect ();
$ names = $ reader -> value ( ' name ' )-> collectLazy ();要素が特定の属性を含む特定の要素または値を検索することをお勧めします。これを行うには、 valueまたはelementメソッドに2番目の引数を提供します。これにより、最後の要素が属性を検索し、一致する場合に戻ります。
$ 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を検索する素晴らしい方法です。 1つの文字列を使用すると、特定の属性またはインデックスを使用して、特定の要素を検索できます。 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ドキュメントには適していない場合があります。
UN -PREFIXED xmlns属性を含むXMLドキュメントがあることに気付くかもしれません - 次のようになります。
< container xmlns = " http://example.com/xml-wrangler/person " xmlns : xsi = " http://www.w3.org/2001/XMLSchema-instance " />これが発生すると、XMLラングラーはこれらの非洗浄されていない名前空間を自動的に削除して互換性を向上させます。これらの名前空間を保持したい場合は、 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を書くときは、要素の属性と名前空間を定義する必要があることがよくあります。 XMLの配列のElementクラスを使用して、属性または名前空間を持つ要素を追加できます。 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と同じスタンドアロン属性を解釈しません）。これをカスタマイズしたい場合は、Writerの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"?> 。
addProcessingInstructionメソッドを使用して、XMLにカスタム「処理命令」を追加できます。
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は縮小されていません。 XMLを監督するためのwrite方法に3番目の引数を提供できます。
use Saloon XmlWrangler XmlWriter ;
$ xml = XmlWriter :: make ()-> write ( ' root ' , [...], minified: true );XMLラングラーは、多くのレッグワークを行う2つの非常に強力なライブラリの周りのシンプルなラッパーです。両方の図書館は素晴らしく、星に値します！
