Configuration

Configuration

This library provides several layers of configuration to control version-specific behavior, serialization, and unserialization.

Version Configuration

Each supported FHIR version has a Version class implementing VersionInterface. This class lives at the root of each version's namespace and serves as the entry point for version-specific configuration, type maps, and FHIR version metadata.

For example, the R4 version class: DCarbone\PHPFHIRGenerated\Versions\R4\Version.

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Version;

// Create with default configuration
$version = new Version();

// Access version metadata
echo $version->getName();                // "R4"
echo $version->getFHIRSemanticVersion(); // "v4.0.1"
echo $version->getFHIRShortVersion();    // "v4.0"

VersionConfig

The VersionConfig class bundles together both serialization and unserialization configuration for a given version. It can be passed to the Version constructor, or configured after creation:

<?php

use DCarbone\PHPFHIRGenerated\Encoding\SerializeConfig;
use DCarbone\PHPFHIRGenerated\Encoding\UnserializeConfig;
use DCarbone\PHPFHIRGenerated\Versions\VersionConfig;
use DCarbone\PHPFHIRGenerated\Versions\R4\Version;

// Configure via constructor
$versionConfig = new VersionConfig(
    unserializeConfig: new UnserializeConfig(jsonDecodeMaxDepth: 1024),
    serializeConfig: new SerializeConfig(rootXMLNS: 'http://hl7.org/fhir'),
);

$version = new Version($versionConfig);

// Or configure via arrays
$version = new Version([
    'unserializeConfig' => ['jsonDecodeMaxDepth' => 1024],
    'serializeConfig' => ['rootXMLNS' => 'http://hl7.org/fhir'],
]);

Serialization Configuration

The SerializeConfig class controls how resources are encoded to JSON or XML.

Option	Type	Default	Description
overrideSourceXMLNS	bool	false	If true, overrides the xmlns found at the root of a source XML document when re-serializing.
rootXMLNS	?string	null	The XML namespace to write on the root element. If null, uses the source namespace (if any).
xhtmlLibxmlOpts	int	LIBXML_NONET | ...	Libxml option mask used when loading XHTML values into XMLReader for serialization. See libxml constants.

<?php

use DCarbone\PHPFHIRGenerated\Encoding\SerializeConfig;

$config = new SerializeConfig(
    overrideSourceXMLNS: true,
    rootXMLNS: 'http://hl7.org/fhir',
);

Unserialization Configuration

The UnserializeConfig class controls how JSON and XML are decoded into FHIR type instances.

Option	Type	Default	Description
libxmlOpts	int	LIBXML_NONET | ...	Libxml option mask used when decoding XML. See libxml constants.
jsonDecodeMaxDepth	int	512	Maximum nesting depth for JSON decoding.
jsonDecodeOpts	int	JSON_BIGINT_AS_STRING	Option mask for json_decode(). See JSON constants.

<?php

use DCarbone\PHPFHIRGenerated\Encoding\UnserializeConfig;

$config = new UnserializeConfig(
    jsonDecodeMaxDepth: 1024,
    jsonDecodeOpts: JSON_BIGINT_AS_STRING | JSON_THROW_ON_ERROR,
);

Note: JSON_BIGINT_AS_STRING is enabled by default to prevent buffer overflow or data mutation when decoding large numeric values. Override jsonDecodeOpts only if you know what you are doing.

Configuration Precedence

When using the unserialization methods directly on a type (e.g., FHIRPatient::jsonUnserialize()), you may optionally pass an UnserializeConfig instance. If omitted, a default instance with sane defaults is created automatically.

When using the VersionClient or ResourceParser, configuration is drawn from the Version object's VersionConfig.