> For the complete documentation index, see [llms.txt](https://php-fhir-tools.ardenexal.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://php-fhir-tools.ardenexal.net/code-generation/overview.md).
# Overview
The Code Generation component loads FHIR packages from the registry and generates strongly-typed PHP classes from their definitions. A `StructureDefinition` is FHIR's machine-readable description of a resource or data type, and a `ValueSet` is a named set of permitted codes. The generator turns them into Resources, DataTypes, Primitives, and Enums. It is the engine behind the [`fhir:generate`](/code-generation/base-models.md) and [`fhir:generate-ig`](/code-generation/implementation-guides.md) console commands.
Namespace: `Ardenexal\FHIRTools\Component\CodeGeneration\`.
There are two distinct workflows:
## How it works
Both commands share the same pipeline, implemented with [Nette PhpGenerator](https://github.com/nette/php-generator):
1. **Package loading** — `PackageLoader` downloads and caches FHIR packages (`.tgz`) from the FHIR registry (`packages.fhir.org`), verifying integrity and resolving versions. Cached packages can be reused with `--offline`.
2. **Definition parsing** — `loadPackageStructureDefinitions()` reads `StructureDefinition` and `ValueSet` JSON resources out of each package into a per-version `BuilderContext`.
3. **Class generation** — each `StructureDefinition` is routed by its `kind` to a generator that emits a PHP class or enum:
* `kind: resource` → Resources (`PatientResource`, `ObservationResource`, …)
* `kind: complex-type` → DataTypes (`HumanName`, `Address`, …)
* `kind: primitive-type` → Primitives (`StringPrimitive`, `BooleanPrimitive`, …)
* referenced `ValueSet` bindings → Enums (`AdministrativeGender`, …) plus a `…Type` code wrapper class in `DataType/`
`fhir:generate` runs in three global phases — **load** all requested packages, **clear** only the output directories for the affected FHIR versions, then **generate** — so generating one version never clobbers another. It skips `logical` models and `derivation: constraint` definitions (profiles and named extensions); those are the domain of [`fhir:generate-ig`](/code-generation/implementation-guides.md).
### Core classes
| Class | Location under `…\CodeGeneration\` | Responsibility |
| ------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------- |
| `PackageLoader` | `Package\PackageLoader` | Download, cache, extract, and parse FHIR packages |
| `BuilderContext` | `Context\BuilderContext` | Hold definitions, generated types, enums, and namespace registrations during a run |
| `FHIRModelGenerator` | `Generator\FHIRModelGenerator` | Generate a PHP class from a base `StructureDefinition` |
| `FHIRValueSetGenerator` | `Generator\FHIRValueSetGenerator` | Generate a PHP enum from a `ValueSet` |
| `FHIRExtensionGenerator` | `Generator\FHIRExtensionGenerator` | Generate typed extension classes (`type: Extension`) |
| `FHIRProfileGenerator` | `Generator\FHIRProfileGenerator` | Generate profile subclasses (`derivation: constraint`) |
| `ErrorCollector` | `Generator\ErrorCollector` | Collect non-fatal errors/warnings for end-of-run reporting |
See [Base FHIR Models](/code-generation/base-models.md) for the generator APIs in detail and [Implementation Guides](/code-generation/implementation-guides.md) for the extension/profile generators.
{% hint style="warning" %}
Generated model files under `src/Component/Models/src/` are **never hand-edited** — always regenerate. See [Generated Output Structure](/code-generation/output-structure.md).
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://php-fhir-tools.ardenexal.net/code-generation/overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.