Skip to content

Builder Usage

Jump to bottom
Daniel Carbone edited this page Jan 14, 2025 · 1 revision

The only supported mechanisms to use this library are "standalone" and "composer dependency". Both require the following:

  1. PHP 8.1 or newer.
  2. composer.
  3. Extracted FHIR version schema(s).

Supported FHIR versions

You will need to download and extract the desired FHIR schema XSD's yourself prior to using this library. You can find the complete list of schemas here: hl7.org/fhir/history.html

Version Documentation Schema Download
DSTU1 (v0.0.82) https://hl7.org/fhir/DSTU1/index.html https://hl7.org/fhir/DSTU1/fhir-all-xsd.zip
DSTU2 (v1.0.2) https://hl7.org/fhir/DSTU2/index.html https://hl7.org/fhir/DSTU2/fhir-codegen-xsd.zip
STU3 (v3.0.2) https://hl7.org/fhir/STU3/index.html https://hl7.org/fhir/STU3/fhir-codegen-xsd.zip
R4 (v4.0.1) https://hl7.org/fhir/R4/index.html https://hl7.org/fhir/R4/fhir-codegen-xsd.zip
R4B (v4.3.0) https://hl7.org/fhir/R4B/index.html https://hl7.org/fhir/R4B/fhir-codegen-xsd.zip
R5 (v5.0.0) https://hl7.org/fhir/R5/index.html https://hl7.org/fhir/R5/fhir-codegen-xsd.zip

You can include as many versions as you wish when running the generator, including multiple copies of the same version with different configuration / naming, if you wish.

Once you have downloaded your desired version(s), extract each version's .xsd files into a separate directory.

NOTE: The files must be located in the ROOT of the directory, the generator does not recurse into sub-directories to find .xsd files.

Recommended Directory Structure

It is recommended you extract each version's .xsd files into a directory named the same as your version, and under a common parent.

For example, if you wish to interact with R4 and R5 resources with the same client:

mkdir -p fhir-schemas \
    && pushd fhir-schemas \
    && mkdir -p R4 \
    && mkdir -p R5 \
    && wget -O- https://hl7.org/fhir/R4/fhir-codegen-xsd.zip > R4.zip \
    && wget -O- https://hl7.org/fhir/R5/fhir-codegen-xsd.zip > R5.zip \
    && unzip R4.zip -d R4 \
    && unzip R5.zip -d R5 \
    && popd

This will download the schemas for R4 and R5, unzipping them into version-specific directories under a fhir-schema parent directory. A similar structure will be assume for all future examples.

Standalone Usage

  1. Use git to check out or download the source for the desired version of php-fhir.
  2. Navigate to root of checked out / downloaded and expanded code.
  3. Execute composer install.
  4. Download and extract your desired FHIR version schema files
  5. Define configuration and execute.

Standalone Example Script

Below is an example script to generate code for FHIR versions R4 and R5:

<?php declare(strict_types=1);

# require composer autoloader
require __DIR__ . '/vendor/autoload.php';

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

# define configuration values

$output_dir = 'set the desired output path here.';
$root_namespace = 'set the desired root namespace here';
$version_config = [
  [
    'name' => 'R4',
    'namespace' => 'Versions\\R4',
    'schemaPath' => 'set path to extracted R4 schema .xsd files here',
  ],
  [
    'name' => 'R5',
    'namespace' => 'Versions\\R5',
    'schemaPath' => 'set path to extracted R5 schema .xsd files here',
  ],
];

# create configuration object

$config = new Config(
   outputPath: $output_path,
   rootNamespace: $root_namespace,
   versions: $version_config,
);

# create builder object

$builder = new Builder($config);

# generate code

$builder->render();

If the provided configuration was sane, you should now have several thousand PHP files generated under the path you set to $output_path.

Install as Composer Dependency

To use this library as a composer dependency, simply execute the following from the root of your composer project:

composer require dcarbone/php-fhir

From there, usage is identical to the Standalone option.

Clone this wiki locally