README

PHP library for generating FHIR model classes from StructureDefinitions. Produces PHP classes, data types, primitives, and enums from FHIR Implementation Guide packages.

Features

Generate PHP classes from FHIR StructureDefinitions
Generate PHP enums from FHIR ValueSets
Package management with FHIR registry integration
Semantic version resolution and dependency handling
Local package caching with integrity verification
Offline mode for air-gapped environments

How It Works

The code generation pipeline:

Package Loading — Downloads and caches FHIR IG packages (.tgz) from packages.fhir.org
Definition Parsing — Reads StructureDefinition and ValueSet JSON resources from the package
Class Generation — Produces PHP classes using Nette PhpGenerator:
- Resources (Patient, Observation, etc.)
- Data Types (HumanName, Address, etc.)
- Primitives (FHIRString, FHIRInteger, etc.)
- Backbone Elements (nested within parent resource namespaces)
Enum Generation — Produces PHP enums from required ValueSets (AdministrativeGender, etc.)

Usage

Generation is driven through the fhir:generate console command:

# Generate R4 models
php bin/console fhir:generate --package=hl7.fhir.r4.core -vvv

# Generate R4B models
php bin/console fhir:generate --package=hl7.fhir.r4b.core -vvv

# Generate multiple versions at once
php bin/console fhir:generate --package=hl7.fhir.r4.core --package=hl7.fhir.r4b.core -vvv

# Offline mode (cached packages only)
php bin/console fhir:generate --package=hl7.fhir.r4.core --offline -vvv

The terminology package (hl7.terminology.r4) is automatically included as a dependency.

Composer Scripts

composer run generate-models-r4      # R4 only
composer run generate-models-r4b     # R4B only
composer run generate-models-all     # R4 + R4B + R5

Core Classes

FHIRModelGenerator

Generates PHP classes from individual StructureDefinitions:

use Ardenexal\FHIRTools\Component\CodeGeneration\Generator\FHIRModelGenerator;

// Called internally by the generate command for each StructureDefinition
$classType = $generator->generate($structureDefinition, $version, $builderContext);

FHIRValueSetGenerator

Generates PHP enums from ValueSet definitions:

use Ardenexal\FHIRTools\Component\CodeGeneration\Generator\FHIRValueSetGenerator;

$enumType = $generator->generateEnum($valueSetDefinition, $version, $builderContext);

PackageLoader

Manages FHIR package downloads, caching, and extraction:

use Ardenexal\FHIRTools\Component\CodeGeneration\Package\PackageLoader;

// Install a package (downloads if not cached)
$metadata = $loader->installPackage('hl7.fhir.r4.core', '4.0.1');

// Load StructureDefinitions into the build context
$definitions = $loader->loadPackageStructureDefinitions($metadata);

// Check cache
$isCached = $loader->isPackageCached('hl7.fhir.r4.core', '4.0.1');

BuilderContext

Holds state during generation — loaded definitions, generated classes, namespace registrations:

use Ardenexal\FHIRTools\Component\CodeGeneration\Context\BuilderContext;

$context = new BuilderContext();
$context->addDefinition($url, $definition);

Error Handling

use Ardenexal\FHIRTools\Component\CodeGeneration\Exception\GenerationException;
use Ardenexal\FHIRTools\Component\CodeGeneration\Exception\PackageException;

try {
    $metadata = $loader->installPackage('hl7.fhir.r4.core');
} catch (PackageException $e) {
    // Package download, extraction, or integrity failures
} catch (GenerationException $e) {
    // Code generation failures
}

Non-fatal errors are collected via ErrorCollector and reported at the end of generation.

Requirements

PHP: 8.3 or higher

License

This component is released under the MIT License. See the LICENSE file for details.

ardenexal / fhir-code-generation

Maintainers

Details