Skip to content

Commit e0faa1c

Browse files
JackieDoJackieDo
committed
Update README.md
1 parent 78ecab1 commit e0faa1c

1 file changed

Lines changed: 190 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 190 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,8 @@ Look at one of the following sessions to learn more about this package.
2020
- [Overview](#overview)
2121
- [Installation](#installation)
2222
- [Basic usage](#basic-usage)
23-
- [Convert XML to array](#convert-xml-to-array)
24-
- [Convert XML to Json](#convert-xml-to-json)
25-
- [Convert array to XML](#convert-array-to-xml)
26-
- [Convert array to DOM](#convert-array-to-dom)
23+
- [Convert from XML](#convert-from-xml)
24+
- [Convert from array](#convert-from-array)
2725
- [Advanced usage](#advanced-usage)
2826
- [Set configuration](#set-configuration)
2927
- [Method 1](#method-1)
@@ -33,6 +31,14 @@ Look at one of the following sessions to learn more about this package.
3331
- [Default configuration](#default-configuration)
3432
- [For Xml2Array](#for-xml2array)
3533
- [For Array2Xml](#for-array2xml)
34+
- [Effect of configuration settings](#effect-of-configuration-settings)
35+
- [version](#version)
36+
- [encoding](#encoding)
37+
- [standalone](#standalone)
38+
- [attributesKey, cdataKey, valueKey](#attributeskey-cdatakey-valuekey)
39+
- [namespacesOnRoot](#namespacesonroot)
40+
- [rootElement](#rootelement)
41+
- [keyFixer](#keyfixer)
3642
- [License](#license)
3743

3844
## Installation
@@ -44,17 +50,25 @@ $ composer require jackiedo/xml-array
4450

4551
## Basic usage
4652

47-
### Convert XML to array
53+
### Convert from XML
4854

49-
**Syntax**:
55+
Web have two following methods:
5056

57+
**Convert to array**:
58+
59+
```php
60+
Xml2Array::convert(DOMDocument|SimpleXMLElement|string $inputXML)->toArray();
5161
```
52-
array Xml2Array::convert(DOMDocument|SimpleXMLElement|string $inputXML)->toArray();
62+
63+
**Convert to Json**:
64+
65+
```php
66+
Xml2Array::convert(DOMDocument|SimpleXMLElement|string $inputXML)->toJson(int $flag = 0);
5367
```
5468

5569
> **Note:** The input XML can be one of types DOMDocument object, SimpleXMLElement object or well-formed XML string.
5670
57-
**Example 1** - _(Convert from XML string)_:
71+
**Example 1**: - _(Convert from XML string)_
5872

5973
```php
6074
use Jackiedo\XmlArray\Xml2Array;
@@ -143,7 +157,7 @@ $array = [
143157
]
144158
```
145159

146-
**Example 2** - _(Convert form XML object, such as SimpleXMLElement)_:
160+
**Example 2**: - _(Convert form XML object, such as SimpleXMLElement)_
147161

148162
```php
149163
use Jackiedo\XmlArray\Xml2Array;
@@ -337,26 +351,26 @@ $array = [
337351
];
338352
```
339353

340-
### Convert XML to Json
341-
342-
**Syntax**:
343-
344-
```
345-
string Xml2Array::convert(DOMDocument|SimpleXMLElement|string $inputXML)->toJson([int $options = 0]);
346-
```
347-
348-
**Example 3**:
354+
**Example 3**: - _(Convert to Json)_
349355

350356
```php
351357
$jsonString = Xml2Array::convert($xmlString)->toJson(JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
352358
```
353359

354-
### Convert array to XML
360+
### Convert from array
361+
362+
We also have two following methods:
355363

356-
**Syntax**:
364+
**Convert to XML string**:
357365

366+
```php
367+
Array2Xml::convert(array $array)->toXml(bool $prettyOutput = false);
358368
```
359-
string Array2Xml::convert(array $array)->toXml([bool $prettyOutput = false]);
369+
370+
**Convert to DOMDocument object**:
371+
372+
```php
373+
Array2Xml::convert(array $array)->toDom();
360374
```
361375

362376
**Example 4**:
@@ -369,14 +383,6 @@ use Jackiedo\XmlArray\Array2Xml;
369383
$xmlString = Array2Xml::convert($array)->toXml(true);
370384
```
371385

372-
### Convert array to DOM
373-
374-
**Syntax**:
375-
376-
```
377-
DOMDocument Array2Xml::convert(array $array)->toDom();
378-
```
379-
380386
**Example 5**:
381387

382388
```php
@@ -386,15 +392,16 @@ $domObject = Array2Xml::convert($array)->toDom();
386392
## Advanced usage
387393

388394
### Set configuration
389-
You can set configuration for conversion process with one of following methods:
395+
If we want to change the settings for the conversion process, we can do it in the following ways:
390396

391397
#### Method 1
392398

393399
```php
394400
...
395401
$config = [
396402
'valueKey' => '@text',
397-
'cdataKey' => '@cdata-section'
403+
'cdataKey' => '@cdata-section',
404+
...
398405
];
399406

400407
$array = Xml2Array::convert($inputXml, $config)->toArray();
@@ -421,7 +428,7 @@ $array = $converter->setConfig($config)->convertFrom($inputXml)->toArray();
421428
```
422429

423430
### Get configuration
424-
If you implemented the conversion process using methods 2 and 3, you can get configuration of the conversion with method:
431+
If we implemented the conversion process using methods 2 and 3, we can get configuration of the conversion with method:
425432

426433
```php
427434
$config = $converter->getConfig();
@@ -435,10 +442,11 @@ $config = $converter->getConfig();
435442
$defaultConfig = [
436443
'version' => '1.0', // Version of XML document
437444
'encoding' => 'UTF-8', // Encoding of XML document
445+
'standalone' => null, // Standalone directive for XML document
438446
'attributesKey' => '@attributes', // The key name use for storing attributes of node
439447
'cdataKey' => '@cdata', // The key name use for storing value of Cdata Section in node
440448
'valueKey' => '@value', // The key name use for storing text content of node
441-
'namespacesOnRoot' => true // Collapse all the namespaces on the root node, otherwise it will put in the nodes for which the namespace first appeared.
449+
'namespacesOnRoot' => true // Collapse all the namespaces at the root node, otherwise it will put in the nodes for which the namespace first appeared.
442450
];
443451
```
444452

@@ -448,12 +456,161 @@ $defaultConfig = [
448456
$defaultConfig = [
449457
'version' => '1.0', // Version of XML document
450458
'encoding' => 'UTF-8', // Encoding of XML document
459+
'standalone' => null, // Standalone directive for XML document
451460
'attributesKey' => '@attributes', // The key name use for storing attributes of node
452461
'cdataKey' => '@cdata', // The key name use for storing value of Cdata Section in node
453462
'valueKey' => '@value', // The key name use for storing text content of node
454463
'rootElement' => null, // The name of root node will be create automatically in process of conversion
464+
'keyFixer' => true, // The automatically key normalization will be used during conversion. It can be bool|string|numeric|callable
455465
];
456466
```
457467

468+
### Effect of configuration settings
469+
470+
#### version
471+
472+
| Use in | Data type |
473+
| -------------------- | --------- |
474+
| Xml2Array, Array2Xml | string |
475+
476+
**Effect**: This setting allows specifying the XML version to be generated (in Array2Xml), or reconstructed from the XML string (in Xml2Array)
477+
478+
#### encoding
479+
480+
| Use in | Data type |
481+
| -------------------- | --------- |
482+
| Xml2Array, Array2Xml | string |
483+
484+
**Effect**: This setting is to indicate the encoding type of the XML to be generated (in Array2Xml), or reconstructed from the XML string (in Xml2Array)
485+
486+
#### standalone
487+
488+
| Use in | Data type |
489+
| -------------------- | --------- |
490+
| Xml2Array, Array2Xml | null|bool |
491+
492+
**Effect**: This setting is to allow the `standalone` directive to appear in the XML or not. If it is set to `null`, this directive will not appear.
493+
494+
**Example**:
495+
496+
```php
497+
$xml = Array2Xml::convert($array, [
498+
'standalone' => true
499+
])->toXml(true);
500+
```
501+
502+
Content in $xml will be
503+
504+
```xml
505+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
506+
...
507+
```
508+
509+
#### attributesKey, cdataKey, valueKey
510+
511+
| Use in | Data type |
512+
| -------------------- | --------- |
513+
| Xml2Array, Array2Xml | string |
514+
515+
**Effect**: This setting allows the use of special keywords to contain the values ​​of properties, CDATA section... during the conversion process.
516+
517+
**Example**: Please review the examples above for more detailed understanding.
518+
519+
#### namespacesOnRoot
520+
521+
| Use in | Data type |
522+
| --------- | --------- |
523+
| Xml2Array | bool |
524+
525+
**Effect**: This setting allows to collect all the parsed XML namespaces and place them in the root node. If it is set to `false`, the namespaces will be located at the nodes where it is declared.
526+
527+
**Example**: We use the `Example 1` above again, but this time the configuration is different:
528+
529+
```php
530+
$array = Xml2Array::convert($xmlString, [
531+
'namespacesOnRoot' => false
532+
])->toArray();
533+
```
534+
535+
After running this piece of code `$array` will contain:
536+
537+
```php
538+
$array = [
539+
"root_node" => [
540+
"tag" => "Example tag",
541+
"attribute_tag" => [
542+
"@value" => "Another tag with attributes",
543+
"@attributes" => [
544+
"description" => "This is a tag with attribute"
545+
]
546+
],
547+
...
548+
"example:with_namespace" => [
549+
"@attributes" => [
550+
"xmlns:example" => "http://example.com"
551+
]
552+
"example:sub" => "Content"
553+
],
554+
]
555+
]
556+
```
557+
558+
You see, the `xlmns:example` namespace is put at the `example:with_namespace` key, not at `root_node` as it was originally.
559+
560+
#### rootElement
561+
562+
| Use in | Data type |
563+
| --------- | --------- |
564+
| Array2Xml | string |
565+
566+
**Effect**: According to the Well-formed XML standard, the XML content is only allowed to have a single Root node. This setting allows to wrap all the elements of the original array into a single root node, instead of having to manually edit your array.
567+
568+
#### keyFixer
569+
570+
| Use in | Data type |
571+
| --------- | ---------------------------- |
572+
| Array2Xml | bool|string|numeric|callable |
573+
574+
**Effect**:
575+
576+
According to the Well-formed XML standard, the tag names and attributes must satisfy a number of requirements, in which naming is specified as follows:
577+
578+
- Only allowed to start with aphabet characters and underscore.
579+
- Only accept the `[a-zA-Z]`, `-`, `_`, `.`, `:` characters. In which, the `:` is used to indicate the namespace prefix.
580+
- Do not allow to end with `:`
581+
582+
During conversion, array key names that violate these rules are automatically normalized. If you do not agree to this normalization, set this setting to `false`.
583+
584+
By default, this normalization replaces invalid characters with underscores (`_`). You can change to another character as you like.
585+
586+
**Example**:
587+
588+
```php
589+
// Do not use the key normalization
590+
$xml = Array2Xml::convert($array, [
591+
'keyFixer' => false
592+
])->toXml();
593+
594+
// Use the key normalization with default character (_)
595+
$xml = Array2Xml::convert($array, [
596+
'keyFixer' => true
597+
])->toXml();
598+
599+
// Replace with '---'
600+
$xml = Array2Xml::convert($array, [
601+
'keyFixer' => '---'
602+
])->toXml();
603+
604+
// Use a callable for fixing
605+
$xml = Array2Xml::convert($array, [
606+
'keyFixer' => function ($key) {
607+
$key = str_replace('/', '_', $key);
608+
$key = str_replace('\\' , '.', $key);
609+
610+
return $key;
611+
}
612+
])->toXml();
613+
```
614+
458615
# License
459616
[MIT](LICENSE) © Jackie Do

0 commit comments

Comments
 (0)