Fhir Path Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ardenexal/fhir-path
   

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

2. Basic Usage

   use Ardenexal\FhirPath\FhirPath;
   
   $fhirPath = new FhirPath();
   $result = $fhirPath->evaluate('Patient.name', [
       'resourceType' => 'Patient',
       'name' => [
           ['family' => 'Doe', 'given' => ['John']]
       ]
   ]);
   // Returns: [["family" => "Doe", "given" => ["John"]]]
   

3. First Use Case Query FHIR resources (e.g., JSON/XML) stored in a database or API response:

   $patientData = json_decode(file_get_contents('patient.json'), true);
   $activeAllergies = $fhirPath->evaluate('Patient.allergyIntolerance.where(active=true)', $patientData);
   

Implementation Patterns

Common Workflows

1. Querying Nested FHIR Resources Use dot notation for hierarchical access:

   $observations = $fhirPath->evaluate('Observation.valueQuantity.value', $bundle);
   

2. Filtering with Predicates Combine where() and logical operators:

   $criticalPatients = $fhirPath->evaluate(
       'Patient.where(condition.where(code.coding.where(system="http://loinc.org" and code="38161-5")).exists())',
       $data
   );
   

3. Integration with Eloquent Store FHIR JSON in a fhir_resources table and query via a model:

   class FhirResource extends Model {
       protected $casts = ['data' => 'array'];
   
       public function scopeActiveAllergies($query) {
           return $query->whereRaw("JSON_CONTAINS(data, '$.resourceType', 'Patient')")
                       ->where(function($q) {
                           $q->whereJsonContains('data->allergyIntolerance', '$.active', true);
                       });
       }
   }
   

4. Batch Processing Process FHIR bundles efficiently:

   $bundle = json_decode($apiResponse, true);
   $entries = collect($bundle['entry'] ?? []);
   $results = $entries->map(fn($entry) => $fhirPath->evaluate('Patient.name', $entry['resource']));
   

Performance Tips

• Cache Evaluations: Store frequent queries (e.g., Patient.id) in a config or cache layer.
• Pre-filter Data: Reduce payload size before evaluation (e.g., extract only relevant resources from a bundle).

Gotchas and Tips

Pitfalls

1. Case Sensitivity FHIR paths are case-sensitive. Use exact matches for resource types (Patient ≠ patient).

2. Null Handling Undefined paths return null. Use exists() or default values:

   $fhirPath->evaluate('Patient.deceasedDateTime', $data, null);
   

3. Complex Predicates Overly nested where() clauses may hit PHP recursion limits. Break into smaller queries or use collect() for preprocessing.

4. JSON vs. Array Input The package expects arrays, not JSON strings. Decode responses first:

   $data = json_decode($jsonString, true); // Required!
   

Debugging

• Enable Logging: Wrap evaluations in try-catch to log malformed paths:

  try {
      $result = $fhirPath->evaluate('Patient.???', $data);
  } catch (\Ardenexal\FhirPath\Exception\EvaluationException $e) {
      Log::error("FHIR Path Error: " . $e->getMessage());
  }
  

• Validate Input: Use json_validate() or a library like spatie/array-to-object to sanitize FHIR data before evaluation.

Extension Points

1. Custom Functions Extend the evaluator by registering custom functions (if the package supports it):

   $fhirPath->registerFunction('customFunc', function($arg) {
       return strtoupper($arg);
   });
   // Usage: `Patient.name.where(given.customFunc())`
   

2. Integration with FHIR SDKs Pair with hl7-fhir/php-fhir for validation before evaluation:

   use HL7\FHIR\Parser;
   $parser = new Parser();
   $resource = $parser->parseResource($jsonString);
   $fhirPath->evaluate('Patient.birthDate', $resource->toArray());
   

3. Testing Mock FHIR data in tests:

   $mockPatient = [
       'resourceType' => 'Patient',
       'birthDate' => '1980-01-01'
   ];
   $this->assertEquals('1980-01-01', $fhirPath->evaluate('Patient.birthDate', $mockPatient));