README

Intended Use

This library provides a (read-only) data object for HL7 v3 XML data which can be converted to a PHP array, \stdClass object, or JSON string. It is not intended for modifying the data structure or exporting XML.

Supported Versions/Formats

<Insert documentation about which HL7 v3 (i.e. C-CDA) implementations are supported here>

Library Installation Requirements

How to Use

Including the Library in your Project with Composer

You can manually add the library to your project's composer.json file or use the following command:

composer require uhin/ccda-parser

Then be sure to include the Composer bootstrap file:

include_once('vendor/autoload.php');

Instantiating a Data Object

There are factory methods for creating the data object from a (valid) XML file:

$ccdaDocument = \Uhin\Ccda\Models\CcdaDocument::getDocumentFromFilepath('/path/to/ccda.xml');

from a (valid) XML string:

$ccdaDocument = \Uhin\Ccda\Models\CcdaDocument::getDocumentFromXmlString('<ClinicalDocument />');

and from a \SimpleXMLElement object:

$ccdaDocument = \Uhin\Ccda\Models\CcdaDocument::getDocumentFromSimpleXmlElement($simpleXmlElement);

Accessing the Data Object's Properties

Once you have created the \Uhin\Ccda\Models\CcdaDocument object, you can access its attributes directly:

// The XML data is stored as a \SimpleXMLElement object
$ccdaDocument->simpleXmlElement

// The data object converts that XML data into an array (i.e. dictionary)
$ccdaDocument->data

Converting the Data Object into Desired Formats

You can use the data object's conversion methods to get the XML data in different formats:

// Get the data as an array (i.e. dictionary)
$ccdaDocument->toArray()

// Get the data as a \stdClass object
$ccdaDocument->toStdClass()

// Get the data as a JSON-encoded string
$ccdaDocument->toJson()

// Also returns a JSON-encoded string (used for type-casting to a string)
$ccdaDocument->__toString()
(string) $ccdaDocument

Notes about Structure

This basic XML data:

<ClinicalDocument xmlns:randomNamespace="http://www.w3.org/2001/XMLSchema-instance">
    <globalChild randomNamespace:namespacedAttribute="random value 1" globalAttribute="random value 2">global child value</globalChild>
    <randomNamespace:namespacedChild randomNamespace:namespacedAttribute="random value 3" globalAttribute="random value 4">namespaced child value</randomNamespace:namespacedChild>
</ClinicalDocument>

will be converted into this JSON object:

{
	"ClinicalDocument": {
		"randomNamespace": {
			"namespacedChild": {
				"randomNamespace": {
					"attribute:namespacedAttribute": "random value 3"
				},
				"attribute:globalAttribute": "random value 4",
				"value": "namespaced child value"
			}
		},
		"globalChild": {
			"randomNamespace": {
				"attribute:namespacedAttribute": "random value 1"
			},
			"attribute:globalAttribute": "random value 2",
			"value": "global child value"
		}
	}
}

Because attribute names can conflict with the names of child elements (or there can be a value attribute which would conflict with the way the XML element value is parsed), attributes are prepended with a prefix and a prefix delimiter. The default prefix is attribute and the default prefix delimiter is : (colon). If you would like to use a different prefix and/or delimiter, simply set the following attributes:

$ccdaDocument->elementAttributePrefix = 'differentAttributePrefix'
$ccdaDocument->elementAttributePrefixDelimiter = '-'

And the data attribute and conversion methods will all be updated with the new structure:

{
	"ClinicalDocument": {
		"randomNamespace": {
			"namespacedChild": {
				"randomNamespace": {
					"differentAttributePrefix-namespacedAttribute": "random value 3"
				},
				"differentAttributePrefix-globalAttribute": "random value 4",
				"value": "namespaced child value"
			}
		},
		"globalChild": {
			"randomNamespace": {
				"differentAttributePrefix-namespacedAttribute": "random value 1"
			},
			"differentAttributePrefix-globalAttribute": "random value 2",
			"value": "global child value"
		}
	}
}

Additional Information

About Us

Utah Health Information Network (UHIN) is a non-profit organization in the healthcare industry with goals of improving patient outcomes and reducing healthcare costs. If you are using any of our open source projects or would like to know more about us, we would love to hear from you.

www.uhin.org

Email UHIN Customer Service

Phone: 801-716-5901

Toll Free: 877-693-3071

Address: 1226 E 6600 S Murray, UT 84121

Also, be sure to check out our other projects on GitHub and our knowledge center for more information about healthcare.

uhin / ccda-parser-library

Maintainers

Details