| [ Index ] |
PHP Cross Reference of YOURLS |
[Summary view] [Print] [Text view]
1 # Convert an array to xml 2 3 [](https://github.com/spatie/array-to-xml/releases) 4 [](LICENSE.md) 5  6 [](https://packagist.org/packages/spatie/array-to-xml) 7 8 This package provides a very simple class to convert an array to an xml string. 9 10 ## Support us 11 12 [<img src="https://github-ads.s3.eu-central-1.amazonaws.com/array-to-xml.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/array-to-xml) 13 14 We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). 15 16 We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). 17 18 ## Install 19 20 You can install this package via composer. 21 22 ``` bash 23 composer require spatie/array-to-xml 24 ``` 25 26 ## Usage 27 28 ```php 29 use Spatie\ArrayToXml\ArrayToXml; 30 ... 31 $array = [ 32 'Good guy' => [ 33 'name' => 'Luke Skywalker', 34 'weapon' => 'Lightsaber' 35 ], 36 'Bad guy' => [ 37 'name' => 'Sauron', 38 'weapon' => 'Evil Eye' 39 ] 40 ]; 41 42 $result = ArrayToXml::convert($array); 43 ``` 44 After running this piece of code `$result` will contain: 45 46 ```xml 47 <?xml version="1.0"?> 48 <root> 49 <Good_guy> 50 <name>Luke Skywalker</name> 51 <weapon>Lightsaber</weapon> 52 </Good_guy> 53 <Bad_guy> 54 <name>Sauron</name> 55 <weapon>Evil Eye</weapon> 56 </Bad_guy> 57 </root> 58 ``` 59 60 61 ### Setting the name of the root element 62 63 Optionally you can set the name of the rootElement by passing it as the second argument. If you don't specify 64 this argument (or set it to an empty string) "root" will be used. 65 ``` 66 $result = ArrayToXml::convert($array, 'customrootname'); 67 ``` 68 69 ### Handling key names 70 71 By default all spaces in the key names of your array will be converted to underscores. If you want to opt out of 72 this behaviour you can set the third argument to false. We'll leave all keynames alone. 73 ``` 74 $result = ArrayToXml::convert($array, 'customrootname', false); 75 ``` 76 77 ### Adding attributes 78 79 You can use a key named `_attributes` to add attributes to a node, and `_value` to specify the value. 80 81 ```php 82 $array = [ 83 'Good guy' => [ 84 '_attributes' => ['attr1' => 'value'], 85 'name' => 'Luke Skywalker', 86 'weapon' => 'Lightsaber' 87 ], 88 'Bad guy' => [ 89 'name' => 'Sauron', 90 'weapon' => 'Evil Eye' 91 ], 92 'The survivor' => [ 93 '_attributes' => ['house'=>'Hogwarts'], 94 '_value' => 'Harry Potter' 95 ], 96 'Good movie' => [ 97 '_attributes' => ['category' => 'Action'], 98 '_value' => 300, 99 ], 100 ]; 101 102 $result = ArrayToXml::convert($array); 103 ``` 104 105 This code will result in: 106 107 ```xml 108 <?xml version="1.0"?> 109 <root> 110 <Good_guy attr1="value"> 111 <name>Luke Skywalker</name> 112 <weapon>Lightsaber</weapon> 113 </Good_guy> 114 <Bad_guy> 115 <name>Sauron</name> 116 <weapon>Evil Eye</weapon> 117 </Bad_guy> 118 <The_survivor house="Hogwarts"> 119 Harry Potter 120 </The_survivor> 121 <Good_movie category="Action">300</Good_movie> 122 </root> 123 ``` 124 125 *Note, that the value of the `_value` field must be a string. [(More)](https://github.com/spatie/array-to-xml/issues/75#issuecomment-413726065)* 126 127 ### Adding comments 128 129 You can use a key named `_comment` to add a comment to a node. The exact placement depends on where you put the key in your array. You can also add multiple keys *starting with* `_comment` to add multiple comments. 130 131 ```php 132 $array = [ 133 'Good guy' => [ 134 '_comment' => 'Our hero', 135 'name' => 'Luke Skywalker', 136 'weapon' => 'Lightsaber' 137 ], 138 'Bad guy' => [ 139 'name' => 'Sauron', 140 'weapon' => 'Evil Eye', 141 '_comment' => 'Finally gone', 142 ], 143 'Another guy' => [ 144 '_comment' => 'The GOAT', 145 'name' => 'John Wick', 146 '_comment2' => 'famous for', 147 'weapon' => 'Pencil', 148 '_comment_other' => 'His dog needs an entry', 149 ]; 150 'The survivor' => [ 151 '_attributes' => ['house'=>'Hogwarts'], 152 '_value' => 'Harry Potter', 153 '_comment' => 'He made it', 154 ] 155 ]; 156 157 $result = ArrayToXml::convert($array); 158 ``` 159 160 This code will result in: 161 162 ```xml 163 <?xml version="1.0"?> 164 <root> 165 <Good_guy> 166 <!--Our hero--> 167 <name>Luke Skywalker</name> 168 <weapon>Lightsaber</weapon> 169 </Good_guy> 170 <Bad_guy> 171 <name>Sauron</name> 172 <weapon>Evil Eye</weapon> 173 <!--Finally gone--> 174 </Bad_guy> 175 <Another_guy> 176 <!--The GOAT--> 177 <name>John Wick</name> 178 <!--famous for--> 179 <weapon>Pencil</weapon> 180 <!--His dog needs an entry--> 181 </Another_guy> 182 <The_survivor house="Hogwarts">Harry Potter<!--He made it--></The_survivor> 183 </root> 184 ``` 185 186 > [!NOTE] 187 > A comment will be omitted if the value is an empty string "" or `null`. 188 189 ### Using reserved characters 190 191 It is also possible to wrap the value of a node into a CDATA section. This allows you to use reserved characters. 192 193 ```php 194 $array = [ 195 'Good guy' => [ 196 'name' => [ 197 '_cdata' => '<h1>Luke Skywalker</h1>' 198 ], 199 'weapon' => 'Lightsaber' 200 ], 201 'Bad guy' => [ 202 'name' => '<h1>Sauron</h1>', 203 'weapon' => 'Evil Eye' 204 ] 205 ]; 206 207 $result = ArrayToXml::convert($array); 208 ``` 209 210 This code will result in: 211 212 ```xml 213 <?xml version="1.0"?> 214 <root> 215 <Good_guy> 216 <name><![CDATA[<h1>Luke Skywalker</h1>]]></name> 217 <weapon>Lightsaber</weapon> 218 </Good_guy> 219 <Bad_guy> 220 <name><h1>Sauron</h1></name> 221 <weapon>Evil Eye</weapon> 222 </Bad_guy> 223 </root> 224 ``` 225 226 If your input contains something that cannot be parsed a `DOMException` will be thrown. 227 228 229 ### Customize the XML declaration 230 231 You could specify specific values in for: 232 - encoding as the fourth argument (string) 233 - version as the fifth argument (string) 234 - DOM properties as the sixth argument (array) 235 - standalone as seventh argument (boolean) 236 237 ```php 238 $result = ArrayToXml::convert($array, [], true, 'UTF-8', '1.1', [], true); 239 ``` 240 241 This will result in: 242 243 ```xml 244 <?xml version="1.1" encoding="UTF-8" standalone="yes"?> 245 ``` 246 247 248 ### Adding attributes to the root element 249 250 To add attributes to the root element provide an array with an `_attributes` key as the second argument. 251 The root element name can then be set using the `rootElementName` key. 252 253 ```php 254 $result = ArrayToXml::convert($array, [ 255 'rootElementName' => 'helloyouluckypeople', 256 '_attributes' => [ 257 'xmlns' => 'https://github.com/spatie/array-to-xml', 258 ], 259 ], true, 'UTF-8'); 260 ``` 261 262 ### Using a multi-dimensional array 263 264 Use a multi-dimensional array to create a collection of elements. 265 ```php 266 $array = [ 267 'Good guys' => [ 268 'Guy' => [ 269 ['name' => 'Luke Skywalker', 'weapon' => 'Lightsaber'], 270 ['name' => 'Captain America', 'weapon' => 'Shield'], 271 ], 272 ], 273 'Bad guys' => [ 274 'Guy' => [ 275 ['name' => 'Sauron', 'weapon' => 'Evil Eye'], 276 ['name' => 'Darth Vader', 'weapon' => 'Lightsaber'], 277 ], 278 ], 279 ]; 280 ``` 281 282 This will result in: 283 284 ```xml 285 <?xml version="1.0" encoding="UTF-8"?> 286 <helloyouluckypeople xmlns="https://github.com/spatie/array-to-xml"> 287 <Good_guys> 288 <Guy> 289 <name>Luke Skywalker</name> 290 <weapon>Lightsaber</weapon> 291 </Guy> 292 <Guy> 293 <name>Captain America</name> 294 <weapon>Shield</weapon> 295 </Guy> 296 </Good_guys> 297 <Bad_guys> 298 <Guy> 299 <name>Sauron</name> 300 <weapon>Evil Eye</weapon> 301 </Guy> 302 <Guy> 303 <name>Darth Vader</name> 304 <weapon>Lightsaber</weapon> 305 </Guy> 306 </Bad_guys> 307 </helloyouluckypeople> 308 ``` 309 310 ### Using Closure values 311 The package can use Closure values: 312 313 ```php 314 $users = [ 315 [ 316 'name' => 'one', 317 'age' => 10, 318 ], 319 [ 320 'name' => 'two', 321 'age' => 12, 322 ], 323 ]; 324 325 $array = [ 326 'users' => function () use ($users) { 327 $new_users = []; 328 foreach ($users as $user) { 329 $new_users[] = array_merge( 330 $user, 331 [ 332 'double_age' => $user['age'] * 2, 333 ] 334 ); 335 } 336 337 return $new_users; 338 }, 339 ]; 340 341 ArrayToXml::convert($array) 342 ``` 343 344 This will result in: 345 346 ```xml 347 <?xml version="1.0"?> 348 <root> 349 <users> 350 <name>one</name> 351 <age>10</age> 352 <double_age>20</double_age> 353 </users> 354 <users> 355 <name>two</name> 356 <age>12</age> 357 <double_age>24</double_age> 358 </users> 359 </root> 360 ``` 361 362 ### Handling numeric keys 363 364 The package can also can handle numeric keys: 365 366 ```php 367 $array = [ 368 100 => [ 369 'name' => 'Vladimir', 370 'nickname' => 'greeflas', 371 ], 372 200 => [ 373 'name' => 'Marina', 374 'nickname' => 'estacet', 375 ], 376 ]; 377 378 $result = ArrayToXml::convert(['__numeric' => $array]); 379 ``` 380 381 This will result in: 382 383 ```xml 384 <?xml version="1.0" encoding="UTF-8"?> 385 <root> 386 <numeric_100> 387 <name>Vladimir</name> 388 <nickname>greeflas</nickname> 389 </numeric_100> 390 <numeric_200> 391 <name>Marina</name> 392 <nickname>estacet</nickname> 393 </numeric_200> 394 </root> 395 ``` 396 397 You can change key prefix with setter method called `setNumericTagNamePrefix()`. 398 399 ### Using custom keys 400 401 The package can also can handle custom keys: 402 403 ```php 404 $array = [ 405 '__custom:custom-key:1' => [ 406 'name' => 'Vladimir', 407 'nickname' => 'greeflas', 408 ], 409 '__custom:custom-key:2' => [ 410 'name' => 'Marina', 411 'nickname' => 'estacet', 412 'tags' => [ 413 '__custom:tag:1' => 'first-tag', 414 '__custom:tag:2' => 'second-tag', 415 ] 416 ], 417 ]; 418 419 $result = ArrayToXml::convert($array); 420 ``` 421 422 This will result in: 423 424 ```xml 425 <?xml version="1.0" encoding="UTF-8"?> 426 <root> 427 <custom-key> 428 <name>Vladimir</name> 429 <nickname>greeflas</nickname> 430 </custom-key> 431 <custom-key> 432 <name>Marina</name> 433 <nickname>estacet</nickname> 434 <tags> 435 <tag>first-tag</tag> 436 <tag>second-tag</tag> 437 </tags> 438 </custom-key> 439 </root> 440 ``` 441 442 A custom key contains three, colon-separated parts: "__custom:[custom-tag]:[unique-string]". 443 444 - "__custom" 445 - The key always starts with "__custom". 446 - [custom-tag] 447 - The string to be rendered as the XML tag. 448 - [unique-string] 449 - A unique string that avoids overwriting of duplicate keys in PHP arrays. 450 451 a colon character can be included within the custom-tag portion by escaping it with a backslash: 452 453 ```php 454 $array = [ 455 '__custom:ns\\:custom-key:1' => [ 456 'name' => 'Vladimir', 457 'nickname' => 'greeflas', 458 ], 459 '__custom:ns\\:custom-key:2' => [ 460 'name' => 'Marina', 461 'nickname' => 'estacet', 462 'tags' => [ 463 '__custom:ns\\:tag:1' => 'first-tag', 464 '__custom:ns\\:tag:2' => 'second-tag', 465 ] 466 ], 467 ]; 468 ``` 469 This will result in: 470 471 ```xml 472 <?xml version="1.0" encoding="UTF-8"?> 473 <root> 474 <ns:custom-key> 475 <name>Vladimir</name> 476 <nickname>greeflas</nickname> 477 </ns:custom-key> 478 <ns:custom-key> 479 <name>Marina</name> 480 <nickname>estacet</nickname> 481 <tags> 482 <ns:tag>first-tag</ns:tag> 483 <ns:tag>second-tag</ns:tag> 484 </tags> 485 </ns:custom-key> 486 </root> 487 ``` 488 489 ### Setting DOMDocument properties 490 491 To set properties of the internal DOMDocument object just pass an array consisting of keys and values. For a full list of valid properties consult https://www.php.net/manual/en/class.domdocument.php. 492 493 You can use the constructor to set DOMDocument properties. 494 495 ```php 496 $result = ArrayToXml::convert( 497 $array, 498 $rootElement, 499 $replaceSpacesByUnderScoresInKeyNames, 500 $xmlEncoding, 501 $xmlVersion, 502 ['formatOutput' => true] 503 ); 504 505 ``` 506 507 Alternatively you can use `setDomProperties` 508 509 ```php 510 $arrayToXml = new ArrayToXml($array); 511 $arrayToXml->setDomProperties(['formatOutput' => true]); 512 $result = $arrayToXml->toXml(); 513 ``` 514 515 ### XML Prettification 516 517 Call `$arrayToXml->prettify()` method on ArrayToXml to set XML in pretty form. 518 519 Example: 520 521 ```php 522 $array = [ 523 'Good guy' => [ 524 'name' => 'Luke Skywalker', 525 'weapon' => 'Lightsaber' 526 ], 527 'Bad guy' => [ 528 'name' => 'Sauron', 529 'weapon' => 'Evil Eye' 530 ] 531 ]; 532 $arrayToXml = new ArrayToXml($array); 533 ``` 534 535 With prettification: 536 537 ```php 538 $arrayToXml->prettify()->toXml(); 539 ``` 540 541 will result in: 542 543 ```xml 544 <?xml version="1.0"?> 545 <root> 546 <Good_guy> 547 <name>Luke Skywalker</name> 548 <weapon>Lightsaber</weapon> 549 </Good_guy> 550 <Bad_guy> 551 <name>Sauron</name> 552 <weapon>Evil Eye</weapon> 553 </Bad_guy> 554 </root> 555 ``` 556 557 Without prettification: 558 559 ```php 560 $arrayToXml->toXml(); 561 ``` 562 563 will result in: 564 565 ```xml 566 <?xml version="1.0"?> 567 <root><Good_guy><name>Luke Skywalker</name><weapon>Lightsaber</weapon></Good_guy><Bad_guy><name>Sauron</name><weapon>Evil Eye</weapon></Bad_guy></root> 568 ``` 569 570 ### Dropping XML declaration 571 572 Call `$arrayToXml->dropXmlDeclaration()` method on ArrayToXml object to omit default XML declaration on top of the generated XML. 573 574 Example: 575 576 ```php 577 $root = [ 578 'rootElementName' => 'soap:Envelope', 579 '_attributes' => [ 580 'xmlns:soap' => 'http://www.w3.org/2003/05/soap-envelope/', 581 ], 582 ]; 583 $array = [ 584 'soap:Header' => [], 585 'soap:Body' => [ 586 'soap:key' => 'soap:value', 587 ], 588 ]; 589 $arrayToXml = new ArrayToXml($array, $root); 590 591 $result = $arrayToXml->dropXmlDeclaration()->toXml(); 592 ``` 593 594 This will result in: 595 596 ```xml 597 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"><soap:Header/><soap:Body><soap:key>soap:value</soap:key></soap:Body></soap:Envelope> 598 ``` 599 600 ### Adding processing instructions 601 602 Call `$arrayToXml->addProcessingInstruction($target, $data)` method on ArrayToXml object to prepend a processing instruction before the root element. 603 604 Example: 605 606 ```php 607 $arrayToXml = new ArrayToXml($array); 608 $arrayToXml->addProcessingInstruction('xml-stylesheet', 'type="text/xsl" href="base.xsl"'); 609 $result = $arrayToXml->toXml(); 610 ``` 611 612 This will result in: 613 614 ```xml 615 <?xml version="1.0"?> 616 <?xml-stylesheet type="text/xsl" href="base.xsl"?> 617 <root><Good_guy><name>Luke Skywalker</name><weapon>Lightsaber</weapon></Good_guy><Bad_guy><name>Sauron</name><weapon>Evil Eye</weapon></Bad_guy></root> 618 ``` 619 620 ## Testing 621 622 ```bash 623 vendor/bin/phpunit 624 ``` 625 626 ## Changelog 627 628 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. 629 630 ## Contributing 631 632 Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details. 633 634 ## Security Vulnerabilities 635 636 Please review [our security policy](../../security/policy) on how to report security vulnerabilities. 637 638 ## Postcardware 639 640 You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. 641 642 Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium. 643 644 We publish all received postcards [on our company website](https://spatie.be/en/opensource/postcards). 645 646 ## Credits 647 648 - [Freek Van der Herten](https://github.com/freekmurze) 649 - [All Contributors](../../contributors) 650 651 ## License 652 653 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Jan 6 05:10:29 2026 | Cross-referenced by PHPXref 0.7.1 |