> 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/serialization/overview.md).

# Overview

The Serialization component converts FHIR model objects to and from JSON and XML. It works standalone (no framework) or wired through the [Symfony Bundle](/symfony-bundle/configuration.md). It is built on top of the Symfony Serializer component, with FHIR-aware normalizers handling resources, complex types, backbone elements, and primitives.

The public surface is small and stable:

* `FHIRSerializationService` — the high-level entry point (`serializeToJson`, `serializeToXml`, `deserializeFromJson`, `deserializeFromXml`, `deserialize`).
* `FHIRSerializationContext` — an immutable value object describing options. See [Context & Options](/serialization/context.md).
* `Validator\FHIRValidator` — business-rule validation. See [Validation](/validation/overview.md).

Everything else (the per-format normalizers, the type resolver, the metadata extractor) is an internal detail that the service or the Symfony container wires for you. You normally never instantiate those directly.

## Installation

{% tabs %}
{% tab title="Standalone" %}

```bash
composer require ardenexal/fhir-serialization ardenexal/fhir-models
```

`ardenexal/fhir-models` provides the generated R4/R4B/R5 model classes the serializer reads and writes. Without it there is nothing to serialize.
{% endtab %}

{% tab title="With FHIRBundle" %}
The Serialization component is pulled in automatically with the bundle:

```bash
composer require ardenexal/fhir-bundle
```

{% endtab %}
{% endtabs %}

## Creating the service

{% tabs %}
{% tab title="Standalone" %}
Outside a Symfony container, build a fully-wired service with the static factory. It defaults to FHIR R4; pass a different `FhirVersion` for R4B or R5.

```php
<?php

use Ardenexal\FHIRTools\Component\Serialization\FHIRSerializationService;
use Ardenexal\FHIRTools\Component\Serialization\FhirVersion;

$serializer = FHIRSerializationService::createDefault();                 // R4
// $serializer = FHIRSerializationService::createDefault(FhirVersion::R5);
```

{% hint style="warning" %}
**Do not** call `new FHIRSerializationService()` directly — the constructor requires a fully assembled `Serializer`, context factory, and debug-info collector. `createDefault()` (and `createWithIG()`, see [IG-Aware](/serialization/ig-aware.md)) perform that wiring for you.
{% endhint %}
{% endtab %}

{% tab title="Symfony DI" %}
When the FHIRBundle is installed, inject the service by type — the `fhir.serialization_service` alias points at it:

```php
<?php

namespace App\Service;

use Ardenexal\FHIRTools\Component\Serialization\FHIRSerializationService;
use Ardenexal\FHIRTools\Component\Models\R4B\Resource\PatientResource;

final class PatientService
{
    public function __construct(
        private readonly FHIRSerializationService $serializer,
    ) {}

    public function toJson(PatientResource $patient): string
    {
        return $this->serializer->serializeToJson($patient);
    }
}
```

{% endtab %}
{% endtabs %}

## Next

* [JSON Serialization](/serialization/json.md)
* [XML Serialization](/serialization/xml.md)
* [Context & Options](/serialization/context.md)
* [IG-Aware Serialization](/serialization/ig-aware.md)


---

# 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/serialization/overview.md?ask=<question>
```

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.