Skip to content

Contributing

Jump to bottom
Daniel Carbone edited this page Apr 2, 2026 · 1 revision

Contributing

Thank you for your interest in contributing to php-fhir! This page covers the development workflow, code layout, and conventions used in the project.

Development Setup

git clone https://github.com/dcarbone/php-fhir.git
cd php-fhir
composer install

You will also need extracted FHIR schema XSDs in the input/ directory if you intend to run generation or generated-code tests. The default bin/config.php expects one sub-directory per version:

input/
├── DSTU1/
├── DSTU2/
├── STU3/
├── R4/
├── R4B/
└── R5/

See Getting Started for download links.

Repository Layout

php-fhir/
├── bin/              CLI entry points (generate.sh, generate.php, config.php)
├── files/            Autoloaded constants and helper functions
│   ├── constants.php    Global constants (paths, namespace segments, entity names)
│   └── funcs.php        require_with(), pretty_var_export()
├── input/            Extracted FHIR XSD schemas (one dir per version)
├── output/           Default generation output (src/ + tests/)
├── phpunit/          PHPUnit bootstrap and per-target XML configs
├── src/              Generator source code
│   ├── Builder.php        Orchestrates the render pipeline
│   ├── Config.php         Top-level configuration
│   ├── CoreFile.php       Single generated entity metadata
│   ├── CoreFiles.php      Collection of CoreFile for a template dir
│   ├── Logger.php         PSR-3 wrapper with break-logging
│   ├── Version.php        A configured FHIR version
│   ├── Builder/           Import tracking, type builder helpers
│   ├── Config/            VersionConfig
│   ├── Enum/              Generator-side enums (TypeKindEnum, PrimitiveTypeEnum, …)
│   ├── Render/            Templates static renderer
│   ├── Utilities/         File, name, import, copyright, doc, type-hint utilities
│   └── Version/           Definition, SourceMetadata, VersionDefaultConfig, type model
├── template/         PHP template files that produce generated code
│   ├── core/             Shared library entities (interfaces, traits, client, encoding, …)
│   ├── versions/         Per-version entities + per-type class templates
│   └── tests/            Test class templates (core + per-version + per-type)
├── tests/            Generator unit tests
└── vendor/           Composer dependencies

How Code Generation Works (Quick Summary)

  1. User creates a Config with one or more VersionConfig entries.
  2. Builder::render() is called.
  3. Core files — templates under template/core/ are rendered and written to the library path.
  4. Per-version core — templates under template/versions/core/ are rendered for each version.
  5. Per-version types — FHIR XSDs are parsed into a Definition → Types graph, then each Type is rendered using template/versions/types/ templates.
  6. Tests — the same process repeats for template/tests/.

See Architecture for the full pipeline description.

Template Conventions

  • Templates are plain .php files that return a string of generated PHP code.
  • Filename prefix determines the entity type: class_, interface_, trait_, enum_, exception_, test_.
  • Templates receive variables via extract() — typically $config, $version, $type, or $coreFile.
  • Sub-templates are included using the global require_with() helper (defined in files/funcs.php) which provides a clean variable scope per include.

Coding Style

  • PHP 8.1+ — use typed properties, enums, named arguments, match, union types.
  • declare(strict_types=1) on every file.
  • Private properties are prefixed with _ (e.g. $_config, $_types).
  • PSR-4 autoloading under DCarbone\PHPFHIR\ → src/.
  • No external runtime dependencies beyond psr/log and composer/semver.

Running Tests

See the Testing page for full details. Quick reference:

# Generator unit tests
vendor/bin/phpunit -c phpunit/Builder.xml

# Generate + test R4
PHPFHIR_TEST_TARGET=R4 vendor/bin/phpunit -c phpunit/R4.xml

# Core only (no FHIR versions)
PHPFHIR_TEST_TARGET=Core vendor/bin/phpunit -c phpunit/Core.xml

Pull Request Guidelines

  1. Fork and branch from the latest release branch.
  2. Keep changes focused — one feature or fix per PR.
  3. Add or update tests where applicable.
  4. Run the generator and generated-code tests for at least one FHIR version before submitting.
  5. Follow the existing code style (see above).

License

php-fhir is released under the Apache License 2.0. By contributing you agree that your contributions will be licensed under the same terms.

← Back to Home

Clone this wiki locally