Skip to content

Getting Started

Jump to bottom
Daniel Carbone edited this page Apr 21, 2026 · 2 revisions

Getting Started

Prerequisites

Requirement Details
PHP 8.1 or newer
Composer https://getcomposer.org/
PHP extensions ctype, curl, dom, json, libxml, simplexml, xmlreader, xmlwriter
FHIR schemas One or more extracted FHIR version XSD bundles (see below)

Supported FHIR Versions

Download and extract the XSD schemas for every FHIR version you want to generate code for. The full list of official releases is at hl7.org/fhir/history.html.

Version Documentation Schema Download
DSTU1 (v0.0.82) DSTU1 Docs fhir-all-xsd.zip
DSTU2 (v1.0.2) DSTU2 Docs fhir-codegen-xsd.zip
STU3 (v3.0.2) STU3 Docs fhir-codegen-xsd.zip
R4 (v4.0.1) R4 Docs fhir-codegen-xsd.zip
R4B (v4.3.0) R4B Docs fhir-codegen-xsd.zip
R5 (v5.0.0) R5 Docs fhir-codegen-xsd.zip
R6 ballot (pre-release) R6 Docs Check hl7.org/fhir/history.html for the latest ballot drop

Note on R6 ballot builds: these versions carry a pre-release suffix in their schema version string (e.g. v6.0.0-ballot4). php-fhir handles this automatically — the suffix is parsed out of the fhir-base.xsd header and exposed via Version::getFHIRPreRelease() and Version::isFHIRPreRelease(). All Semver range checks use only the base vX.Y.Z portion, so isR6() returns true for ballot builds as expected.

You can generate code for as many versions as you like in a single run.

Important: .xsd files must be placed in the root of each version directory — the generator does not recurse into sub-directories.

Recommended Directory Layout

fhir-schemas/
├── R4/          ← extracted .xsd files for R4
├── R5/          ← extracted .xsd files for R5
└── ...

Example download commands for R4 and R5:

mkdir -p fhir-schemas && cd fhir-schemas
mkdir R4 R5
curl -Lo R4.zip https://hl7.org/fhir/R4/fhir-codegen-xsd.zip
curl -Lo R5.zip https://hl7.org/fhir/R5/fhir-codegen-xsd.zip
unzip R4.zip -d R4
unzip R5.zip -d R5

Installation

Option A — Standalone (clone the repo)

  1. Clone or download a release from https://github.com/dcarbone/php-fhir/releases.
  2. Install dependencies: 
    cd php-fhir
composer install
  3. Download and extract your desired FHIR schemas (see above).
  4. Either use the CLI generator or write a small PHP script (see below).

Option B — Composer dependency

Add php-fhir to your own project:

composer require dcarbone/php-fhir

Usage is then identical to the standalone option — create a Config, pass it to Builder, and call render().

Minimal Generation Script

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use DCarbone\PHPFHIR\Builder;
use DCarbone\PHPFHIR\Config;
use DCarbone\PHPFHIR\Config\VersionConfig;

$config = new Config(
    libraryPath: __DIR__ . '/generated/src',
    versions: [
        new VersionConfig(name: 'R4', schemaPath: __DIR__ . '/fhir-schemas/R4'),
        new VersionConfig(name: 'R5', schemaPath: __DIR__ . '/fhir-schemas/R5'),
    ],
    testsPath: __DIR__ . '/generated/tests',   // optional — omit to skip test generation
);

$builder = new Builder($config);
$builder->render();

echo "Done!\n";

After a successful run, the generated/src directory will contain several thousand PHP files organised under the configured namespace (default: DCarbone\PHPFHIRGenerated).

For the full list of configuration options, see Configuration Reference.

Next: CLI Usage →

Clone this wiki locally