|
1 | 1 | # Derafu: XML - Library for XML manipulation |
2 | 2 |
|
3 | | - |
4 | | - |
5 | | - |
6 | | - |
7 | | - |
8 | | - |
9 | | - |
10 | | -A comprehensive PHP library for XML manipulation, providing robust tools for encoding, decoding, validating, and querying XML documents. |
11 | | - |
12 | | -## Features |
13 | | - |
14 | | -- **Conversion**: Transform between XML and PHP arrays in both directions. |
15 | | -- **Validation**: Validate XML documents against XSD schemas. |
16 | | -- **Querying**: Powerful XPath querying with parameter support. |
17 | | -- **Canonicalization**: Support for C14N and ISO-8859-1 encoding. |
18 | | -- **Encoding**: Proper handling of character encoding between UTF-8 and ISO-8859-1. |
19 | | -- **Special Characters**: Automatic handling of XML special characters and entities. |
20 | | - |
21 | | -## Installation |
22 | | - |
23 | | -```bash |
24 | | -composer require derafu/xml |
25 | | -``` |
26 | | - |
27 | | -## Basic Usage |
28 | | - |
29 | | -### Creating XML from an Array |
30 | | - |
31 | | -```php |
32 | | -use Derafu\Xml\Service\XmlEncoder; |
33 | | - |
34 | | -$encoder = new XmlEncoder(); |
35 | | - |
36 | | -// Create an array to convert to XML. |
37 | | -$data = [ |
38 | | - 'root' => [ |
39 | | - 'element1' => 'value1', |
40 | | - 'element2' => 'value2', |
41 | | - 'element3' => [ |
42 | | - '@attributes' => [ |
43 | | - 'attr1' => 'attrValue', |
44 | | - ], |
45 | | - '@value' => 'value3', |
46 | | - ], |
47 | | - 'repeatedElement' => ['value4', 'value5', 'value6'], |
48 | | - ], |
49 | | -]; |
50 | | - |
51 | | -// Convert the array to XML. |
52 | | -$xmlDocument = $encoder->encode($data); |
53 | | - |
54 | | -// Save as XML string. |
55 | | -$xmlString = $xmlDocument->saveXml(); |
56 | | - |
57 | | -// Get the XML without the XML declaration. |
58 | | -$xmlContent = $xmlDocument->getXml(); |
59 | | - |
60 | | -// Get a canonicalized version of the XML. |
61 | | -$c14nXml = $xmlDocument->C14N(); |
62 | | - |
63 | | -// Get a canonicalized version with ISO-8859-1 encoding. |
64 | | -$isoXml = $xmlDocument->C14NWithIso88591Encoding(); |
65 | | -``` |
66 | | - |
67 | | -### Converting XML to an Array |
68 | | - |
69 | | -```php |
70 | | -use Derafu\Xml\Service\XmlDecoder; |
71 | | -use Derafu\Xml\XmlDocument; |
72 | | - |
73 | | -$decoder = new XmlDecoder(); |
74 | | - |
75 | | -// Load an existing XML string. |
76 | | -$xmlContent = '<?xml version="1.0" encoding="UTF-8"?><root><element>value</element></root>'; |
77 | | -$document = new XmlDocument(); |
78 | | -$document->loadXml($xmlContent); |
79 | | - |
80 | | -// Convert to an array. |
81 | | -$array = $decoder->decode($document); |
82 | | - |
83 | | -// Now $array contains ['root' => ['element' => 'value']] |
84 | | -``` |
85 | | - |
86 | | -### Working with XPath |
87 | | - |
88 | | -```php |
89 | | -use Derafu\Xml\XPathQuery; |
90 | | - |
91 | | -$xmlContent = '<?xml version="1.0"?><root><item id="1">First</item><item id="2">Second</item></root>'; |
92 | | - |
93 | | -// Create XPath query instance. |
94 | | -$query = new XPathQuery($xmlContent); |
95 | | - |
96 | | -// Get a specific value. |
97 | | -$value = $query->getValue('/root/item[@id="2"]'); // "Second" |
98 | | - |
99 | | -// Get multiple values. |
100 | | -$values = $query->getValues('/root/item'); // ["First", "Second"] |
101 | | - |
102 | | -// Get structured array. |
103 | | -$array = $query->get('/root'); |
104 | | -// Result: ['item' => ['First', 'Second']] |
105 | | -``` |
106 | | - |
107 | | -### XML Validation |
108 | | - |
109 | | -```php |
110 | | -use Derafu\Xml\Exception\XmlException; |
111 | | -use Derafu\Xml\Service\XmlValidator; |
112 | | - |
113 | | -$validator = new XmlValidator(); |
114 | | - |
115 | | -// Validate an XML document against a schema. |
116 | | -try { |
117 | | - $validator->validate($xmlDocument, '/path/to/schema.xsd'); |
118 | | - echo "XML is valid!"; |
119 | | -} catch (XmlException $e) { |
120 | | - echo "Validation failed: " . $e->getMessage(); |
121 | | - $errors = $e->getErrors(); // Get detailed error information. |
122 | | -} |
123 | | -``` |
124 | | - |
125 | | -## Advanced Usage |
126 | | - |
127 | | -### Working with Namespaces |
128 | | - |
129 | | -```php |
130 | | -// Create XPath query with namespace support. |
131 | | -$namespaces = ['ns' => 'http://example.com/namespace']; |
132 | | -$query = new XPathQuery($xmlContent, $namespaces); |
133 | | - |
134 | | -// Query with namespace. |
135 | | -$result = $query->get('//ns:Element'); |
136 | | -``` |
137 | | - |
138 | | -### Array Structure for XML Creation |
139 | | - |
140 | | -When creating XML from arrays, the structure follows these conventions: |
141 | | - |
142 | | -- Simple key-value pairs become element nodes. |
143 | | -- Use `@attributes` for node attributes. |
144 | | -- Use `@value` for node text content when attributes are present. |
145 | | -- Arrays of values create repeated nodes with the same name. |
146 | | - |
147 | | -Example: |
148 | | -```php |
149 | | -$data = [ |
150 | | - 'root' => [ |
151 | | - 'element' => [ |
152 | | - '@attributes' => ['id' => '123'], |
153 | | - '@value' => 'content', |
154 | | - ], |
155 | | - 'items' => [ |
156 | | - 'item' => ['value1', 'value2', 'value3'], |
157 | | - ], |
158 | | - ], |
159 | | -]; |
160 | | -``` |
161 | | - |
162 | | -Produces: |
163 | | -```xml |
164 | | -<root> |
165 | | - <element id="123">content</element> |
166 | | - <items> |
167 | | - <item>value1</item> |
168 | | - <item>value2</item> |
169 | | - <item>value3</item> |
170 | | - </items> |
171 | | -</root> |
172 | | -``` |
173 | | - |
174 | | -## Contributing |
175 | | - |
176 | | -Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change. |
177 | | - |
178 | | -## License |
179 | | - |
180 | | -This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). |
| 3 | +Please refer to the [documentation](https://www.derafu.dev/docs/data/xml) for more information. |
0 commit comments