borislavsabev / simple-xml-loader
A minimalistic SimpleXml loader. Wraps the simplexml_load_XXXX() methods and provides error handling.
Installs: 1 456
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- ext-libxml: *
- ext-simplexml: *
Requires (Dev)
- phpunit/phpunit: ^5.7
This package is not auto-updated.
Last update: 2024-10-27 03:01:20 UTC
README
A minimalistic SimpleXml loader. Wraps the simplexml_load_XXXX() methods and provides libxml error handling.
Main goals:
- provide a transparent OOP interface to SimpleXML's
simplexml_load_file()
andsimplexml_load_string()
functions - handle SimpleXML's internal errors
- throw catchable Exceptions (XmlLoaderException)
This wrapper will:
- try to load your XML resource into a \SimpleXMLElement object and return it
- handle any LibXML errors that occur during loading
This wrapper will not:
- do anything else
Installation
This package is available on Packagist and installable via Composer:
composer require borislavsabev/simple-xml-loader
Basic usage
As this is a wrapper the wrapped library's functionality is not covered in this documentation. Please refer to:
There are two main functions in the SimpleXMlLoader:
public function loadFile($filename, $xmlClass = "SimpleXMLElement", $options = 0, $xmlNamespace = "", $isPrefix = false)
public function loadString($data, $xmlClass = "SimpleXMLElement", $options = 0, $xmlNamespace = "", $isPrefix = false)
The loader throws XmlLoaderException on any error that occurs. The exception thrown contains the message and code of the last \LibXmlError. The loader calls are meant to be wrapped in try/catch blocks and read any errors yourself:
use BorislavSabev\SimpleXmlLoader\XmlLoader;
use BorislavSabev\SimpleXmlLoader\Exception\XmlLoaderException;
$xmlLoader = new XmlLoader();
try {
/** @var \SimpleXMLElement $simpleXmlElement */
$simpleXmlElement = $xmlLoader->loadFile($filename);
//Now do something with the loaded \SimpleXMLElement...
} catch (XmlLoaderException $e) {
// The last error is contained in $e:
$e->getMessage();
$e->getCode();
//All errors accessible through the payload:
/** @var array $xmlErrors */
$xmlErrors = $xmlLoader->getXmlPayload()
->getXmlErrors();
}
The XmlLoader instance is meant to be reused thus:
- Each call to
XmlLoader->loadFile()
orXmlLoader->loadString()
will clear any LibXml errors stored - Each call to
XmlLoader->loadFile()
orXmlLoader->loadString()
will replace it's internal XmlLoaderPayload object
Loop usage
Each consecutive call to a loader method resets the state of LibXML and the payload you must extract all data between calls.
use BorislavSabev\SimpleXmlLoader\XmlLoader;
use BorislavSabev\SimpleXmlLoader\Exception\XmlLoaderException;
$xmlLoader = new XmlLoader();
foreach ($aBunchOfXmlStrings as $xmlString) {
try {
/** @var \SimpleXMLElement $simpleXmlElement */
$simpleXmlElement = $xmlLoader->loadString($xmlString);
} catch (XmlLoaderException $e) {
/** @var array $xmlErrors */
$xmlErrors = $xmlLoader->getXmlPayload()
->getXmlErrors();
}
//Any data within LibXML or our XmlLoaderPayload will be lost after this iteration of the loop
}
Reusing XmlLoaderPayload
You can also reuse the XmlLoaderPayload in your application if you which. Say for example you use this wrapper to parse different XML file but then want to pass the result to different Services in your code that will handle any business logic. You could just get the XmlLoaderPayload and pass it along to a specific service (or whatever really):
use BorislavSabev\SimpleXmlLoader\XmlLoader;
use BorislavSabev\SimpleXmlLoader\Exception\XmlLoaderException;
$xmlLoader = new XmlLoader();
try {
$xmlLoader->loadFile($filename);
//Generic example:
$serviceBroker->pass(
MyCoolService::class,
$xmlLoader->getXmlPayload()
);
} catch (XmlLoaderException $e) {
/** @var array $xmlErrors */
$xmlErrors = $xmlLoader->getXmlPayload()
->getXmlErrors();
}
NOTE: Generally you should have you own payload objects to pass data around in your Domain. The idea of XmlLoaderPayload is to be internal for XmlLoader thus it cannot contain any logic outside of that task.
Behaviour overwritten
There is only one behaviour change that this library introduces:
"If you pass an empty string to simplexml_load_string()
it will return false and throw no error".
The SimpleXmlLoader wrapper throws an XmlLoaderException
in this case.
The XmlLoaderException and LibXML's libXMLError
XmlLoaderException's codes are specific to this wrapper. LibXML's libXMLError objects are just returned in an array and as received from SimpleXML/LibXML.
Personal Opinion on the SimpleXML PHP Extension
Generally SimpleXML is not a solid PHP extension and, in my mind, it should be used rarely when you need to do something simple fast. Any serious work should be done via DomDocument.
The previous two sentences are the author's personal opinion which as with any opinion should be taken with a grain of salt.
Versioning
This library follows Semver. According to Semver, you will be able to upgrade to any minor or patch version of this library without any breaking changes to the public API. Semver also requires that we clearly define the public API for this library.
All methods, with public
visibility, are part of the public API. All other methods are not part of the public API. Where possible, we'll try to keep protected
methods backwards-compatible in minor/patch versions, but if you're overriding methods then please test your work before upgrading.
Contributing
Please do! PR's are very welcome. The author is far from thinking that this wrapper library is perfect. Any PR must first abide by the [Main goals](#Main goals) set out by this library.
Please note that this project adheres to the Contributor Covenant v1.4. By participating in this project you agree to abide by its terms.