Fhir Metadata Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require ardenexal/fhir-metadata
   

   Ensure your composer.json targets PHP 8.1+ and Laravel 10+.

2. First Use Case: Define a FHIR Resource

   use Ardenexal\FhirMetadata\Interfaces\FhirResourceInterface;
   
   class Patient implements FhirResourceInterface {
       public function getResourceType(): string { return 'Patient'; }
       public function getId(): ?string { return $this->id; }
   }
   

   • Implement FhirResourceInterface to leverage shared validation and utilities.

3. Where to Look First

   • Interfaces: Interfaces/FhirResourceInterface.php (core contract).
   • Traits: Traits/HasId.php, Traits/HasMeta.php (shared logic).
   • Utilities: Utilities/FhirValidator.php, Utilities/FhirSerializer.php (helpers).

Implementation Patterns

1. FHIR Resource Modeling

Pattern: Use traits to standardize FHIR resources.

use Ardenexal\FhirMetadata\Traits\{HasId, HasMeta, HasExtension};

class Observation implements FhirResourceInterface {
    use HasId, HasMeta, HasExtension;

    public string $status;
    public array $code;
}

• Why: Reduces boilerplate for FHIR-specific fields (e.g., id, meta, extension).

2. Validation Workflow

Pattern: Validate resources before serialization.

use Ardenexal\FhirMetadata\Utilities\FhirValidator;

$validator = new FhirValidator();
$errors = $validator->validate($patient);

if ($errors) {
    throw new \InvalidArgumentException("FHIR validation failed: " . implode(', ', $errors));
}

• Tip: Integrate with Laravel’s validation pipeline via a custom rule:

  use Illuminate\Validation\Rule;
  
  Rule::make(function ($attribute, $value, $fail) {
      $validator = new FhirValidator();
      $errors = $validator->validate($value);
      if ($errors) $fail(__('FHIR validation failed'));
  });
  

3. Serialization for APIs

Pattern: Standardize FHIR JSON responses.

use Ardenexal\FhirMetadata\Utilities\FhirSerializer;

$serializer = new FhirSerializer();
return response()->json($serializer->serialize($resource));

• Laravel API Resources: Extend JsonResource to include FHIR metadata:

  public function toArray($request) {
      return [
          'data' => (new FhirSerializer())->serialize($this->resource),
          'meta' => $this->resource->getMeta(),
      ];
  }
  

4. Database Integration

Pattern: Store FHIR resources as JSON or normalize critical fields.

// Option 1: JSON Column
protected $casts = ['fhir_data' => 'array'];

// Option 2: Normalized Fields
protected $fillable = ['id', 'resource_type', 'status', 'code'];

• Tip: Use Laravel’s json casting for dynamic FHIR attributes.

5. Middleware for FHIR Requests

Pattern: Transform incoming FHIR payloads.

namespace App\Http\Middleware;

use Ardenexal\FhirMetadata\Utilities\FhirDeserializer;
use Closure;

class ParseFhirPayload {
    public function handle($request, Closure $next) {
        $deserializer = new FhirDeserializer();
        $request->merge(['fhir_resource' => $deserializer->deserialize($request->getContent())]);
        return $next($request);
    }
}

• Register in app/Http/Kernel.php for FHIR endpoints.

Gotchas and Tips

Pitfalls

1. Undocumented Interfaces

   • Issue: Some methods in FhirResourceInterface may lack PHPDoc or examples.
   • Fix: Inspect src/Interfaces/ and test with minimal implementations:

     class TestResource implements FhirResourceInterface {
         public function getResourceType(): string { return 'Test'; }
         public function getId(): ?string { return null; }
     }
     

2. FHIR Version Mismatches

   • Issue: The package may not explicitly support FHIR R4/R5.
   • Fix: Check for version-specific logic in Utilities/ and validate against a FHIR validator (e.g., fhir-validator).

3. Performance with Large Resources

   • Issue: Complex FHIR resources (e.g., Composition) may cause memory issues during serialization.
   • Fix: Stream responses or use Laravel’s StreamedResponse:

     return response()->stream(function () {
         echo (new FhirSerializer())->serialize($resource);
     });
     

4. Trait Conflicts

   • Issue: Traits like HasId may conflict with Laravel’s HasUuids or HasFactory.
   • Fix: Use fully qualified trait names or alias them:

     use Ardenexal\FhirMetadata\Traits\HasId as FhirHasId;
     

Debugging Tips

• Validate Early: Use FhirValidator in unit tests to catch schema issues:

  public function testPatientValidation() {
      $patient = new Patient(['id' => '1', 'name' => []]); // Missing required 'name'
      $this->assertTrue($validator->validate($patient)->has('name'));
  }
  

• Log FHIR Payloads: Add middleware to log raw FHIR requests/responses:

  \Log::debug('FHIR Request', ['payload' => $request->getContent()]);
  

• Leverage Laravel Tools:
  • Tinker: Inspect FHIR resources interactively:

    php artisan tinker
    >>> $resource = new Patient(['id' => '1']);
    >>> $resource->getMeta()
    

  • Debugbar: Extend laravel-debugbar to display FHIR metadata.

Extension Points

1. Custom Validation Rules

   • Extend FhirValidator to add domain-specific rules:

     class CustomFhirValidator extends FhirValidator {
         protected function rules(): array {
             return array_merge(parent::rules(), [
                 'Patient.name' => ['required', 'array', 'min:1'],
             ]);
         }
     }
     

2. New Resource Types

   • Create a base class for common FHIR resources:

     abstract class BaseFhirResource implements FhirResourceInterface {
         use HasId, HasMeta;
     
         abstract public function getResourceType(): string;
     }
     

3. Integration with FHIR Servers

   • Build a Laravel service to interact with HAPI FHIR or Firebase:

     class FhirServerClient {
         public function fetchResource(string $type, string $id) {
             $response = Http::get("https://fhir-server/fhir/$type/$id");
             return (new FhirDeserializer())->deserialize($response->body());
         }
     }
     

Configuration Quirks

• No Built-in Config: The package likely uses default values. Override via service provider:

  $this->app->singleton(FhirValidator::class, function ($app) {
      return new FhirValidator(config('fhir.validation_rules'));
  });
  

• FHIR Profiles: If using custom profiles, ensure they’re loaded dynamically:

  $validator = new FhirValidator();
  $validator->setProfile('http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient');
  

Testing Strategies

• Unit Tests: Mock FhirResourceInterface to test utilities:

  $mockResource = $this->createMock(FhirResourceInterface::class);
  $mockResource->method('getResourceType')->willReturn('Patient');
  $mockResource->method('getId')->willReturn('123');
  

• Integration Tests: Test API endpoints with real FHIR payloads:

  $response = $this->postJson('/fhir/Patient', $validPatientJson);
  $response->assertStatus(201);
  $this->assertFhirValid($response->json());
  

• FHIR-Specific Assertions: Create custom assertions:

  public function assertFhirValid(array $json) {
      $validator = new FhirValidator();
      $resource = (new FhirDeserializer())->deserialize(json_encode($json));
      $this->assertEmpty($validator->validate($resource));
  }