Fhir Serialization Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ardenexal/fhir-serialization
   

   Ensure your project uses PHP 8.0+ (check composer.json constraints).

2. First Use Case: Parsing FHIR JSON

   use Ardenexal\FhirSerialization\FhirSerializer;
   
   $serializer = new FhirSerializer();
   $fhirData = $serializer->parse('{
       "resourceType": "Patient",
       "id": "example",
       "name": [{"family": "Doe"}]
   }');
   

   • Key Classes:
     • FhirSerializer (core parser)
     • FhirResource (base resource model)
     • FhirBundle (for handling FHIR Bundles)

3. Where to Look First

   • Documentation: Check the PHP-FHIR-Tools ecosystem for FHIR standards.
   • Tests: Browse tests/ for real-world examples (e.g., PatientResourceTest).
   • Source: Focus on src/FhirSerializer.php for core logic.

Implementation Patterns

Workflow: FHIR Resource Handling

1. Deserialization

   $patient = $serializer->parse($jsonString, PatientResource::class);
   // Access fields:
   $patient->getId(); // "example"
   $patient->getName()[0]->getFamily(); // "Doe"
   

2. Validation

   try {
       $serializer->validate($jsonString);
   } catch (FhirValidationException $e) {
       // Handle errors (e.g., missing required fields)
   }
   

3. Bundle Processing

   $bundle = $serializer->parse($bundleJson, FhirBundle::class);
   foreach ($bundle->getEntry() as $entry) {
       $resource = $entry->getResource();
       // Process each resource (Patient, Observation, etc.)
   }
   

Integration Tips

• Laravel Service Provider Bind the serializer to the container for dependency injection:

  $this->app->singleton(FhirSerializer::class, function ($app) {
      return new FhirSerializer();
  });
  

  Use in controllers:

  public function __construct(private FhirSerializer $serializer) {}
  

• Request Handling Parse FHIR payloads from API requests:

  public function store(Request $request) {
      $fhirData = $this->serializer->parse($request->json()->all());
      // Process $fhirData
  }
  

• Testing Use FhirSerializer in feature tests to validate FHIR responses:

  $response = $this->postJson('/api/fhir', $fhirJson);
  $response->assertJson($this->serializer->parse($fhirJson));
  

Gotchas and Tips

Pitfalls

1. Strict FHIR Compliance

   • The package enforces FHIR R4 standards. Non-compliant JSON (e.g., missing resourceType) throws FhirValidationException.
   • Fix: Validate input before parsing or handle exceptions gracefully.

2. Nested Resources

   • Complex nested structures (e.g., Observation with reference fields) require chained parsing:

     $observation = $serializer->parse($json, ObservationResource::class);
     $patientRef = $observation->getSubject(); // FhirReference
     $patient = $serializer->parse($patientRef->getReference(), PatientResource::class);
     

3. Performance

   • Parsing large FHIR Bundles (e.g., 1000+ resources) may hit memory limits.
   • Tip: Stream or chunk processing for large payloads.

Debugging

• Enable Verbose Validation Set the serializer to throw detailed errors:

  $serializer = new FhirSerializer();
  $serializer->setValidationMode(FhirSerializer::VALIDATION_VERBOSE);
  

• Log FHIR Errors Catch FhirValidationException and log the $e->getErrors() array for debugging:

  catch (FhirValidationException $e) {
      \Log::error('FHIR Validation Errors', $e->getErrors());
  }
  

Extension Points

1. Custom Resource Classes Extend FhirResource to add domain-specific logic:

   class CustomPatientResource extends FhirResource {
       public function isActive() {
           return $this->getActive() === true;
       }
   }
   

2. Override Serialization Implement JsonSerializable in custom resources to modify output:

   class CustomBundle extends FhirBundle implements JsonSerializable {
       public function jsonSerialize() {
           $data = parent::jsonSerialize();
           $data['meta'] = ['lastUpdated' => now()->toAtomString()];
           return $data;
       }
   }
   

3. Profile Validation Use the underlying FHIR\R4\Validator for profile-based validation (advanced):

   $validator = $serializer->getValidator();
   $validator->validate($fhirData, 'http://hl7.org/fhir/StructureDefinition/Patient');
   

Config Quirks

• Default FHIR Version The package defaults to FHIR R4. To use another version (e.g., R3), you must manually swap dependencies or fork the package.
• Case Sensitivity FHIR resource types and fields are case-sensitive (e.g., Patient vs patient). Always use uppercase as per the spec.