{"id":20099413,"url":"https://github.com/donatorsky/php-xml-template-reader","last_synced_at":"2025-09-07T21:36:46.733Z","repository":{"id":51857706,"uuid":"354502985","full_name":"donatorsky/php-xml-template-reader","owner":"donatorsky","description":"The PHP XML Reader where you show how to read the XML, and it does the rest for you.","archived":false,"fork":false,"pushed_at":"2021-05-09T19:08:36.000Z","size":57,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-04T20:41:47.254Z","etag":null,"topics":["mapping","php","xml","xml-parser","xml-parsing"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donatorsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"ko_fi":"donatorsky"}},"created_at":"2021-04-04T09:22:49.000Z","updated_at":"2024-09-16T01:56:13.000Z","dependencies_parsed_at":"2022-08-21T07:10:18.480Z","dependency_job_id":null,"html_url":"https://github.com/donatorsky/php-xml-template-reader","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/donatorsky/php-xml-template-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatorsky%2Fphp-xml-template-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatorsky%2Fphp-xml-template-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatorsky%2Fphp-xml-template-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatorsky%2Fphp-xml-template-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donatorsky","download_url":"https://codeload.github.com/donatorsky/php-xml-template-reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatorsky%2Fphp-xml-template-reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274101083,"owners_count":25222444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mapping","php","xml","xml-parser","xml-parsing"],"created_at":"2024-11-13T17:10:23.871Z","updated_at":"2025-09-07T21:36:46.705Z","avatar_url":"https://github.com/donatorsky.png","language":"PHP","funding_links":["https://ko-fi.com/donatorsky"],"categories":[],"sub_categories":[],"readme":"# PHP XML Template Reader\n\nThe PHP XML Reader where you show how to read the XML, and it does the rest for you.\n\n[![GitHub license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/donatorsky/php-xml-template-reader/blob/main/LICENSE)\n[![Build](https://github.com/donatorsky/php-xml-template-reader/workflows/CI/badge.svg?branch=main)](https://github.com/donatorsky/php-xml-template-reader/actions?query=branch%3Amain)\n[![Coverage Status](https://coveralls.io/repos/github/donatorsky/php-xml-template-reader/badge.svg?branch=main)](https://coveralls.io/github/donatorsky/php-xml-template-reader?branch=main)\n\n## How it works\n\nThe PHP XML Template Reader helps You to parse given XML file and create an object from it. The parser uses given template as a schema and tries to match it to input XML, optionally validating it with defined rules.\n\nTo start, simply create new `\\Donatorsky\\XmlTemplate\\Reader\\XmlTemplateReader` object, pass it the template and read using one of available reading modes.\n\n### Example 1\n\nAssuming the following XML:\n\n```xml\n\u003cbooks\u003e\n    \u003cbook ISBN=\"1234567890\"\n          category=\"adventures\"\u003e\n        \u003ctitle\u003eLorem ipsum adventures\u003c/title\u003e\n        ...\n    \u003c/book\u003e\n    ...\n\u003c/books\u003e\n```\n\nYou can already see a pattern, so You can define the template as follows:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbooks\u003e\n        \u003cbook tpl:type=\"collection\"\n              ISBN=\"required | integer\"\n              category=\"\"\u003e\n            \u003ctitle tpl:contents=\"raw\" /\u003e\n            ...\n        \u003c/book\u003e\n        ...\n    \u003c/books\u003e\n\u003c/template\u003e\n```\n\nAs the output You will see an object of type `\\Donatorsky\\XmlTemplate\\Reader\\Models\\Node` (by default, can be changed) with processed data:\n\n```php\nNode {\n    private $nodeName = 'books';\n    \n    private $children = Map [\n        // Because of tpl:type=\"collection\", book element is expected to occur more than 1 times\n        'book' =\u003e Collection [\n            0 =\u003e Node {\n                    private $nodeName = 'book';\n                    \n                    private $attributes = Map [\n                        // You can define set of parsing rules in the template. In this case:\n                        // required | integer\n                        // Means, that value cannot be empty and has to be a valid number. It is also converted to the integer.\n                        'ISBN' =\u003e 1234567890,\n                        \n                        // No filters defined means the value is read \"as is\"\n                        'category' =\u003e 'adventures',\n                    ];\n                    \n                    // By default, tpl:type=\"single\", so title is expected to occur at most 1 time\n                    private $relations = Map [\n                        'title' =\u003e Node {\n                                        private $nodeName = 'title';\n                                        \n                                        private $contents = 'Lorem ipsum adventures';\n                                    },\n                        ...\n                    ];\n                },\n            1 =\u003e ...\n        ]\n    ];\n}\n```\n\nPlease note, that only nodes defined in the template are present in the output Node. When XML changes, You need to update the template.\n\n### Example 2\n\nThe Reader supports namespaced nodes and attributes. In case suggested template's `tpl` namespace conflicts with Yours, feel free to change it to any other XML valid value:\n\n```xml\n\n\u003ctpl:books xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\u003e\n    \u003ctpl:book tpl:ISBN=\"1234567890\"\n              tpl:category=\"adventures\"\u003e\n        \u003ctpl:title\u003eLorem ipsum adventures\u003c/tpl:title\u003e\n        ...\n    \u003c/tpl:book\u003e\n    ...\n\u003c/tpl:books\u003e\n```\n\nYou can already see a pattern, so You can define the template as follows:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:my-namespace=\"http://www.w3.org/2001/XMLSchema-instance\"\n          my-namespace:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003ctpl:books\u003e\n        \u003ctpl:book my-namespace:type=\"collection\"\n                  tpl:ISBN=\"required | integer\"\n                  tpl:category=\"\"\u003e\n            \u003ctpl:title my-namespace:contents=\"raw\" /\u003e\n            ...\n        \u003c/tpl:book\u003e\n        ...\n    \u003c/tpl:books\u003e\n\u003c/template\u003e\n```\n\n## Reading modes\n\nMultiple reading modes are available. Given the following example code:\n\n```php\n$xmlTemplateReader = new \\Donatorsky\\XmlTemplate\\Reader\\XmlTemplateReader(\u003c\u003c\u003c'XML'\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    // ...\n\u003c/template\u003e\nXML\n);\n```\n\n### `read`: read XML from string\n\nYou can provide XML contents and parse it using `read` method:\n\n```php\n$node = $xmlTemplateReader-\u003eread(\u003c\u003c\u003c'XML'\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n// ...\nXML\n);\n```\n\n### `readFile`: read XML from file in given path\n\nYou can provide a path to the XML file and parse it using `readFile` method:\n\n```php\n$node = $xmlTemplateReader-\u003ereadFile('/path/to/file.xml');\n```\n\n### `readStream`: read XML from already opened resource\n\nYou can provide a resource with the XML contents and parse it using `readStream` method:\n\n```php\n$handler = fopen('/path/to/file.xml', 'rb+');\n\n$node = $xmlTemplateReader-\u003ereadStream($handler);\n```\n\n### `open`, `update` and `close`: custom stream XML reading\n\nYou can read the XML chunk by chunk using You own implementation with `open`, `update` and `close` methods:\n\n```php\n$handler = fopen('/path/to/file.xml', 'rb+');\n\n$xmlTemplateReader-\u003eopen();\n\nwhile (!\\feof($handler)) {\n    $this-\u003eupdate(\\fread($handler, 1024));\n}\n\n$node = $xmlTemplateReader-\u003eclose();\n```\n\n## Parsing modifiers\n\nYou can use various parsing modifiers to define some behaviours. Examples below use `tpl` namespace.\n\n### tpl:castTo\n\nAccepted values: class' FQN, must implement `\\Donatorsky\\XmlTemplate\\Reader\\Models\\Contracts\\NodeInterface`.\n\nBy default, when node is parsed, it creates new `\\Donatorsky\\XmlTemplate\\Reader\\Models\\Node` instance with parsed data. However, You can use Your own class. This class must implement `\\Donatorsky\\XmlTemplate\\Reader\\Models\\Contracts\\NodeInterface` interface.\n\n#### Example\n\nDefine node classes:\n\n```php\nnamespace Some\\Name\\Space;\n\nclass BooksNode implements \\Donatorsky\\XmlTemplate\\Reader\\Models\\Contracts\\NodeInterface {\n    // ...\n}\n\n// You can also extend \\Donatorsky\\XmlTemplate\\Reader\\Models\\Node class\nclass SingleBookNode extends \\Donatorsky\\XmlTemplate\\Reader\\Models\\Node {\n    // ...\n    \n    public function getIsbn(): int {\n        return $this-\u003eattributes-\u003eget('ISBN');\n    }\n    \n    public function getCategory(): int {\n        return $this-\u003eattributes-\u003eget('category');\n    }\n}\n```\n\nUse them in the template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbooks tpl:castTo=\"\\Some\\Name\\Space\\BooksNode\"\u003e\n        \u003cbook tpl:type=\"collection\"\n              tpl:castTo=\"\\Some\\Name\\Space\\SingleBookNode\"\n              ISBN=\"required | integer\"\n              category=\"\"\u003e\n            \u003ctitle tpl:contents=\"raw\" /\u003e\n            ...\n        \u003c/book\u003e\n        ...\n    \u003c/books\u003e\n\u003c/template\u003e\n```\n\nThe output:\n\n```php\n$booksNode = Some\\Name\\Space\\BooksNode {\n    private $nodeName = 'books';\n    \n    private $children = \\Donatorsky\\XmlTemplate\\Reader\\Models\\Map [\n        // Because of tpl:type=\"collection\", book element is expected to occur more than 1 times\n        'book' =\u003e \\Donatorsky\\XmlTemplate\\Reader\\Models\\Collection [\n            0 =\u003e Some\\Name\\Space\\SingleBookNode {\n                    private $nodeName = 'book';\n                    \n                    private $attributes = \\Donatorsky\\XmlTemplate\\Reader\\Models\\Map [\n                        // You can define set of parsing rules in the template. In this case:\n                        // required | integer\n                        // Means, that value cannot be empty and has to be a valid number. It is also converted to the integer.\n                        'ISBN' =\u003e 1234567890,\n                        \n                        // No filters defined means the value is read \"as is\"\n                        'category' =\u003e 'adventures',\n                    ];\n                    \n                    // By default, tpl:type=\"single\", so title is expected to occur at most 1 time\n                    private $relations = \\Donatorsky\\XmlTemplate\\Reader\\Models\\Map [\n                        'title' =\u003e \\Donatorsky\\XmlTemplate\\Reader\\Models\\Node {\n                                        private $nodeName = 'title';\n                                        \n                                        private $contents = 'Lorem ipsum adventures';\n                                    },\n                        ...\n                    ];\n                },\n            1 =\u003e ...\n        ]\n    ];\n}\n\n// ...\n\n/**\n * @var \\Some\\Name\\Space\\SingleBookNode $book\n */\nforeach ($booksNode-\u003egetChildren('book') as $book){\n    var_dump($book-\u003egetIsbn(), $book-\u003egetCategory());\n}\n```\n\n### tpl:collectAttributes\n\nAccepted values: `all`, `validated` (default).\n\nBy default, only validated nodes' attributes are collected. This means, that only attributes that are defined in the template are collected. However, You can change it if You also want to collect other attributes.\n\nGiven the input XML:\n\n```xml\n\n\u003cbooks ISBN=\"1234567890\"\n       category=\"adventures\"\u003e\n    ...\n\u003c/books\u003e\n```\n\n#### Example 1\n\nWith the following template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbooks tpl:collectAttributes=\"all\"\n           ISBN=\"\"\u003e\n        ...\n    \u003c/books\u003e\n\u003c/template\u003e\n```\n\nYou will get:\n\n```php\nNode {\n    private $nodeName = 'books';\n    \n    private $attributes = Map [\n        'ISBN'     =\u003e '1234567890',\n        'category' =\u003e 'adventures',\n    ];\n}\n```\n\n#### Example 2\n\nWith the following template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbooks tpl:collectAttributes=\"validated\"\n           ISBN=\"\"\u003e\n        ...\n    \u003c/books\u003e\n\u003c/template\u003e\n```\n\nYou will get:\n\n```php\nNode {\n    private $nodeName = 'books';\n    \n    private $attributes = \\Donatorsky\\XmlTemplate\\Reader\\Models\\Map [\n        'ISBN' =\u003e '1234567890',\n        // 'category' is missing as it is not \"validated\"\n    ];\n}\n```\n\n### tpl:contents\n\nAccepted values: `none` (default when `tpl:type` = collection), `raw` (default when `tpl:type` = single), `trimmed`.\n\nBy default, no node's contents is collected (`none`). This is especially useful for nodes containing other nodes, thus the contents is only a bunch of whitespaces (when XML if pretty-printed). You can change this behaviour and collect raw, unchanged contents (`raw`) of the node or additionally trim whitespaces (`trimmed`).\n\n#### Example\n\nGiven the input XML:\n\n```xml\n\n\u003cbook\u003e\n    \u003ctitle\u003e...\u003c/title\u003e\n\n    \u003cdescription\u003e\n        ...\n        ...\n    \u003c/description\u003e\n\n    \u003cauthors\u003e\n        // ...\n    \u003c/authors\u003e\n\u003c/book\u003e\n```\n\nWith the following template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbook\u003e\n        \u003ctitle tpl:contents=\"raw\" /\u003e\n        \u003cdescription tpl:contents=\"trimmed\" /\u003e\n        \u003cauthors tpl:contents=\"none\" /\u003e\n    \u003c/book\u003e\n\u003c/template\u003e\n```\n\nYou will get:\n\n```php\nNode {\n    private $nodeName = 'books';\n    \n    private $relations = Map [\n        'title' =\u003e Node {\n                        private $nodeName = 'title';\n                        \n                        private $contents = '...';\n                    },\n        'description' =\u003e Node {\n                        private $nodeName = 'title';\n                        \n                        private $contents = '...\n        ...';\n                    },\n        'authors' =\u003e Node {\n                        private $nodeName = 'title';\n                        \n                        private $contents = null;\n                    },\n    ];\n}\n```\n\n### tpl:type\n\nAccepted values: `single` (default), `collection`.\n\nBy default, each node defined in the template is considered to be a single (`single`). However, if You expect multiple elements of the same type, You can change it (`collection`).\n\n#### Example\n\nGiven the input XML:\n\n```xml\n\n\u003cbook\u003e\n    \u003ctitle\u003e...\u003c/title\u003e\n\n    \u003cauthors\u003e\n        \u003cauthor\u003e...\u003c/author\u003e\n        \u003cauthor\u003e...\u003c/author\u003e\n        \u003cauthor\u003e...\u003c/author\u003e\n    \u003c/authors\u003e\n\u003c/book\u003e\n```\n\nWith the following template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbook\u003e\n        \u003ctitle tpl:type=\"single\" /\u003e\n        \u003cauthors\u003e\n            \u003cauthor tpl:type=\"collection\"\u003e\n                // ...\n            \u003c/author\u003e\n        \u003c/authors\u003e\n    \u003c/book\u003e\n\u003c/template\u003e\n```\n\nYou will get:\n\n```php\nNode {\n    private $nodeName = 'books';\n    \n    private $relations = Map [\n        'title' =\u003e Node {\n                        private $nodeName = 'title';\n                    }\n    ];\n    \n    private $children = Map [\n        'author' =\u003e Collection [\n            0 =\u003e Node {\n                    private $nodeName = 'author';\n                },\n            1 =\u003e Node {\n                    private $nodeName = 'author';\n                },\n            2 =\u003e Node {\n                    private $nodeName = 'author';\n                },\n        ]\n    ];\n}\n```\n\n## Rules\n\nRules are simple validators and transformers that can be chained. You can use rules to define attributes constraints and transform them to expected value. Rules may be aliased. Rules can accept additional attributes. Names and aliases are case-insensitive. You can examine built-in rules in `src/Rules` directory, or You can create one by implementing `\\Donatorsky\\XmlTemplate\\Reader\\Rules\\Contracts\\RuleInterface` interface.\n\n### Built-in rules\n\nRule name | Aliases | Validation | Transformation\n--------- | ------- | ---------- | --------------\ncallback | | Custom validation rule | Custom transformation\nfloat | | [Numeric](https://www.php.net/manual/en/function.is-numeric.php) value | Cast to float type\ngreaterThan:threshold | | [Numeric](https://www.php.net/manual/en/function.is-numeric.php) value greater than _threshold_ | Value unchanged\nint | integer | [Numeric](https://www.php.net/manual/en/function.is-numeric.php) value | Cast to int type\nnumeric | | [Numeric](https://www.php.net/manual/en/function.is-numeric.php) value | Cast to int or float type\nrequired | | Value must not be [empty](https://www.php.net/manual/en/function.empty) | Value unchanged\ntrim | | String value | Value is [trimmed](https://www.php.net/manual/en/function.trim)\n\n### Custom rules\n\nTo define custom rule You need to first create a class that implements RuleInterface:\n\n```php\nnamespace Some\\Name\\Space;\n\nclass RegexpRule implements \\Donatorsky\\XmlTemplate\\Reader\\Rules\\Contracts\\RuleInterface {\n\n    private string $pattern;\n    \n    public function __construct(string $pattern) {\n        $this-\u003epattern = $pattern;\n    }\n\n    public function passes($value) : bool {\n        // Validate $value against pattern\n        return (bool) preg_match($this-\u003epattern, $value);\n    }\n    \n    public function process($value) {\n        // Do not modify value\n        return $value;\n    }\n}\n```\n\nThen, You need to register rule class:\n\n```php\n$xmlTemplateReader-\u003eregisterRuleFilter(\n    'regexp', // name\n    \\Some\\Name\\Space\\RegexpRule::class, // Rule class' FQN\n    [\n        'matches',\n    ] // optionalAliases\n);\n```\n\nAnd use it in the template:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003ctemplate xmlns:tpl=\"http://www.w3.org/2001/XMLSchema-instance\"\n          tpl:noNamespaceSchemaLocation=\"./vendor/donatorsky/php-xml-template-reader/xml-template-reader.xsd\"\u003e\n    \u003cbook ISBN=\"regexp:/^\\d{13}$/\"\n          category=\"matches:/^\\w+$/i\"\u003e\n        // ...\n    \u003c/book\u003e\n\u003c/template\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatorsky%2Fphp-xml-template-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonatorsky%2Fphp-xml-template-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatorsky%2Fphp-xml-template-reader/lists"}