Type System

Type System

This library generates a complete set of PHP classes for every FHIR type — resources, elements, backbone elements, and primitives — organized into a hierarchy that mirrors the FHIR specification.

Type Interfaces

All generated types implement a set of core interfaces. Understanding these interfaces helps when writing code that operates generically across multiple FHIR types.

TypeInterface

TypeInterface is the base interface for all FHIR types. It extends \JsonSerializable and provides:

Method	Description
_getFHIRTypeName(): string	The FHIR type name (e.g., "Patient", "HumanName", "string").
_getFHIRVersion(): FHIRVersion	The FHIR version this type belongs to.
_getValidationErrors(): array	Recursively validates this type and all nested fields.
__toString(): string	String representation of the type.

ResourceTypeInterface

ResourceTypeInterface extends TypeInterface and is implemented by all resource-level types. It adds:

Method	Description
_getSourceXMLNS(): ?string	The xmlns from the source XML document (if unserialized from XML).
getId(): ?ResourceIDTypeInterface	The resource's id element.
xmlUnserialize(...)	Static method to unserialize from XML.
xmlSerialize(...)	Instance method to serialize to XML.
jsonUnserialize(...)	Static method to unserialize from JSON.

Other Interfaces

Interface	Purpose
ElementTypeInterface	Implemented by FHIR Element types (complex types that are not resources).
PrimitiveTypeInterface	Implemented by FHIR primitive types (string, integer, boolean, etc.).
PrimitiveContainerTypeInterface	Types that wrap a primitive value (e.g., FHIRString wraps FHIRStringPrimitive).
ValueContainerTypeInterface	Types that contain a single value property.
ContainedTypeInterface	Types that may appear inside a contained element.
ResourceContainerTypeInterface	Types that can hold contained resources.
ResourceIDTypeInterface	The type used for a resource's id field.
CommentContainerInterface	Types that can hold FHIR comments (fhir_comments).

Directory Structure

Types for each FHIR version are organized under:

src/DCarbone/PHPFHIRGenerated/Versions/{VERSION}/Types/

Within each version's Types directory, the classes are nested according to the FHIR type hierarchy. For example, for R4:

Versions/R4/Types/
├── FHIRBooleanPrimitive.php          # Primitive types
├── FHIRStringPrimitive.php
├── FHIRIdPrimitive.php
├── ...
├── FHIRElement.php                   # Base Element type
├── FHIRElement/
│   ├── FHIRBoolean.php              # Element wrappers for primitives
│   ├── FHIRString.php
│   ├── FHIRHumanName.php            # Complex element types
│   ├── FHIRAddress.php
│   └── ...
├── FHIRResource.php                  # Base Resource type
└── FHIRResource/
    ├── FHIRBinary.php
    ├── FHIRBundle.php
    ├── FHIRDomainResource.php
    └── FHIRDomainResource/
        ├── FHIRPatient.php          # Domain resource types
        ├── FHIRObservation.php
        ├── FHIREncounter.php
        └── ...

Primitive Types

FHIR primitives are represented as two classes:

1. FHIR{Type}Primitive — The raw primitive (e.g., FHIRStringPrimitive). Implements PrimitiveTypeInterface.
2. FHIR{Type} — An element wrapper that contains the primitive value and can carry extensions and an id (e.g., FHIRString). Implements PrimitiveContainerTypeInterface.

This two-class pattern allows FHIR's design where even primitive values can carry extensions.

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRStringPrimitive;
use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRElement\FHIRString;

// Raw primitive
$primitive = new FHIRStringPrimitive(value: 'hello');

// Element wrapper (accepts the raw primitive or a plain string)
$element = new FHIRString(value: 'hello');

Version Type Map

Each version provides a VersionTypeMap class implementing VersionTypeMapInterface. This allows looking up FHIR type names to their PHP class names:

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\VersionTypeMap;

// Get the PHP class for a FHIR type name
$className = VersionTypeMap::getTypeClassname('Patient');
// "DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient"

// Check if a type is containable (can appear in Resource.contained)
$isContainable = VersionTypeMap::isContainableType('Patient'); // true
$isContainable = VersionTypeMap::isContainableType('HumanName'); // false

Version-Specific Enums

Each version also provides a VersionResourceTypeEnum with cases for every resource type in that version:

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\VersionResourceTypeEnum;

$type = VersionResourceTypeEnum::PATIENT;
echo $type->value; // "Patient"

This enum is used by the VersionClient for type-safe resource type references.

Working Across Versions

Since each version's types live in a separate namespace, you can work with multiple FHIR versions simultaneously:

<?php

use DCarbone\PHPFHIRGenerated\Versions\R4\Types\FHIRResource\FHIRDomainResource\FHIRPatient as R4Patient;
use DCarbone\PHPFHIRGenerated\Versions\R5\Types\FHIRBase\FHIRResource\FHIRDomainResource\FHIRPatient as R5Patient;

$r4Patient = new R4Patient(id: 'r4-example');
$r5Patient = new R5Patient(id: 'r5-example');

Note: The type hierarchy can change significantly between FHIR versions. Be careful when writing code that targets multiple versions.