Serialization

Serialization

This library supports serializing resources to and from JSON and XML.

Each serialization method has its own set of configurable options that may be specified per-version. See Configuration for more details.

Serializing (Encoding)

Every type implements the JsonSerializable interface and has an xmlSerialize method.

Serializing to JSON

All types implement PHP's \JsonSerializable interface, so you can use json_encode() directly:

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRElement\FHIRHumanName;
use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient;

$patient = new FHIRPatient(
    id: 'patient-1',
    name: [new FHIRHumanName(given: ['Real'], family: 'Human')],
);

$json = json_encode($patient, JSON_PRETTY_PRINT);
echo $json;

Output:

{
    "resourceType": "Patient",
    "id": "patient-1",
    "name": [
        {
            "family": "Human",
            "given": [
                "Real"
            ]
        }
    ]
}

Serializing to XML

Every resource type has an xmlSerialize method that returns an XMLWriter instance. Call outputMemory() on the returned writer to get the XML string:

<?php

use DCarbone\PHPFHIRGenerated\Encoding\SerializeConfig;
use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRElement\FHIRHumanName;
use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient;

$patient = new FHIRPatient(
    id: 'patient-1',
    name: [new FHIRHumanName(given: ['Real'], family: 'Human')],
);

// With default config
$xw = $patient->xmlSerialize();
echo $xw->outputMemory();

// With custom config
$config = new SerializeConfig(rootXMLNS: 'http://hl7.org/fhir');
$xw = $patient->xmlSerialize(config: $config);
echo $xw->outputMemory();

Unserializing (Decoding)

Each type contains static methods for unserializing from JSON and XML.

Unserializing from JSON

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient;

$json = <<<JSON
{
    "resourceType": "Patient",
    "name": [
        {
            "family": "Human",
            "given": ["Real"]
        }
    ]
}
JSON;

$patient = FHIRPatient::jsonUnserialize($json);

The method accepts either a raw JSON string or a pre-decoded \stdClass object.

JSON Decoding Large Numbers

To prevent buffer overflow or mutation of data during unserialization, the JSON_BIGINT_AS_STRING flag is used by default when decoding JSON. You may change this by setting the jsonDecodeOpts field on an UnserializeConfig instance.

JSON Decoding Strings for Numeric Types

Some FHIR servers encode all numeric types (integers and decimals) as strings rather than JSON numbers. This library automatically handles this for all non-string primitive types:

• bool
• integer
• integer64
• positiveInt
• negativeInt
• unsignedInt

Unserializing from XML

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient;

$xml = <<<XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Patient>
    <name>
        <family value="Human"/>
        <given value="Real"/>
    </name>
</Patient>
XML;

$patient = FHIRPatient::xmlUnserialize($xml);

The method accepts either a raw XML string or a \SimpleXMLElement object.

Unserialization Configuration

You do not have to create an UnserializeConfig instance — one with sane defaults will be created automatically if omitted:

<?php

use DCarbone\PHPFHIRGenerated\Encoding\UnserializeConfig;
use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient;

$config = new UnserializeConfig(
    jsonDecodeMaxDepth: 1024,
);

// Pass to jsonUnserialize or xmlUnserialize
$patient = FHIRPatient::jsonUnserialize($json, config: $config);
$patient = FHIRPatient::xmlUnserialize($xml, config: $config);

See Configuration for full details on available options.

PHP Extensions Used

Extension	Purpose
json	JSON encoding/decoding
SimpleXML	XML decoding (unserialization)
XMLWriter	XML encoding (serialization)