feat: add missing ingestion parameters from Langfuse API

README.md

@@ -1,5 +1,7 @@
 ## Langfuse PHP - A PHP Client for Langfuse API
 
+> **For detailed documentation, examples, and parameter references, see the [Wiki](../../wiki).**
+
 This package provides a wrapper around the [Langfuse](https://langfuse.com) API, allowing you to easily integrate Langfuse into your PHP applications. It uses as few dependencies as possible.
 
 ### This package supports the following features:
@@ -134,6 +136,11 @@ $gen = $trace->generation(
     modelParameters: ['temperature' => 0.7],
     promptName: 'my-prompt',
     promptVersion: 1,
+    startTime: '2025-01-01T00:00:00Z',
+    endTime: '2025-01-01T00:00:05Z',
+    completionStartTime: '2025-01-01T00:00:03Z',
+    usageDetails: ['input' => 10, 'output' => 20, 'total' => 30],
+    costDetails: ['input' => 0.001, 'output' => 0.002, 'total' => 0.003],
 );
 
 // Generation nested under a span
@@ -147,7 +154,9 @@ $gen = $span->generation(
 // Update a generation after the LLM responds
 $gen->update(
     output: 'updated response',
-    metadata: ['tokens' => 150],
+    endTime: date('c'),
+    usageDetails: ['input' => 15, 'output' => 25, 'total' => 40],
+    costDetails: ['total' => 0.004],
 );
 ```
 

composer.json

@@ -54,7 +54,7 @@
         "test:lint": "@php vendor/bin/pint --config https://raw.githubusercontent.com/DIJ-digital/pint-config/main/pint.json",
         "test:unit": "pest",
         "test:types": "phpstan",
-        "test:refactor": "rector --dry-run",
+        "test:refactor": "rector",
         "test": [
             "@test:lint",
             "@test:type-coverage",

src/Ingestion.php

@@ -50,6 +50,9 @@ public function trace(
         array|string|null $output = null,
         ?array $metadata = null,
         ?array $tags = null,
+        ?string $release = null,
+        ?string $version = null,
+        ?bool $public = null,
     ): Trace {
         $traceId ??= self::uuid();
 
@@ -63,6 +66,9 @@ public function trace(
             'output' => $output,
             'metadata' => $metadata,
             'tags' => $tags,
+            'release' => $release,
+            'version' => $version,
+            'public' => $public,
             'environment' => $this->environment,
         ], static fn (mixed $v): bool => $v !== null);
 
@@ -91,6 +97,9 @@ public function span(
         ?string $startTime = null,
         ?string $endTime = null,
         ?array $metadata = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): Span {
         $spanId ??= self::uuid();
 
@@ -104,6 +113,9 @@ public function span(
             'input' => $input,
             'output' => $output,
             'metadata' => $metadata,
+            'level' => $level,
+            'statusMessage' => $statusMessage,
+            'version' => $version,
             'environment' => $this->environment,
         ], static fn (mixed $v): bool => $v !== null);
 
@@ -123,6 +135,8 @@ public function span(
      * @param array<string, mixed>|string $output
      * @param array<string, mixed>|null $modelParameters
      * @param array<string, mixed>|null $metadata
+     * @param array<string, int>|null $usageDetails
+     * @param array<string, float>|null $costDetails
      */
     public function generation(
         string $traceId,
@@ -138,6 +152,12 @@ public function generation(
         ?array $metadata = null,
         ?string $startTime = null,
         ?string $endTime = null,
+        ?string $completionStartTime = null,
+        ?array $usageDetails = null,
+        ?array $costDetails = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): Generation {
         $generationId ??= self::uuid();
 
@@ -148,13 +168,19 @@ public function generation(
             'name' => $name,
             'startTime' => $startTime ?? self::now(),
             'endTime' => $endTime,
+            'completionStartTime' => $completionStartTime,
             'input' => $input,
             'output' => $output,
             'model' => $model,
             'modelParameters' => $modelParameters,
             'promptName' => $promptName,
             'promptVersion' => $promptVersion,
             'metadata' => $metadata,
+            'usageDetails' => $usageDetails,
+            'costDetails' => $costDetails,
+            'level' => $level,
+            'statusMessage' => $statusMessage,
+            'version' => $version,
             'environment' => $this->environment,
         ], static fn (mixed $v): bool => $v !== null);
 

src/Ingestion/Generation.php

@@ -26,6 +26,8 @@ public function __construct(
      * @param array<string, mixed>|string|null $output
      * @param array<string, mixed>|null $modelParameters
      * @param array<string, mixed>|null $metadata
+     * @param array<string, int>|null $usageDetails
+     * @param array<string, float>|null $costDetails
      */
     public function update(
         array|string|null $input = null,
@@ -34,6 +36,12 @@ public function update(
         ?array $modelParameters = null,
         ?array $metadata = null,
         ?string $endTime = null,
+        ?string $completionStartTime = null,
+        ?array $usageDetails = null,
+        ?array $costDetails = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): self {
         $body = array_filter([
             'id' => $this->generationId,
@@ -44,6 +52,12 @@ public function update(
             'modelParameters' => $modelParameters,
             'metadata' => $metadata,
             'endTime' => $endTime,
+            'completionStartTime' => $completionStartTime,
+            'usageDetails' => $usageDetails,
+            'costDetails' => $costDetails,
+            'level' => $level,
+            'statusMessage' => $statusMessage,
+            'version' => $version,
         ], static fn (mixed $v): bool => $v !== null);
 
         $this->ingestion->send('generation-update', $body);

src/Ingestion/Span.php

@@ -32,6 +32,9 @@ public function update(
         array|string|null $output = null,
         ?string $endTime = null,
         ?array $metadata = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): self {
         $body = array_filter([
             'id' => $this->spanId,
@@ -41,6 +44,9 @@ public function update(
             'output' => $output,
             'endTime' => $endTime,
             'metadata' => $metadata,
+            'level' => $level,
+            'statusMessage' => $statusMessage,
+            'version' => $version,
         ], static fn (mixed $v): bool => $v !== null);
 
         $this->ingestion->send('span-update', $body);
@@ -63,6 +69,9 @@ public function span(
         ?string $startTime = null,
         ?string $endTime = null,
         ?array $metadata = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): self {
         return $this->ingestion->span(
             traceId: $this->traceId,
@@ -74,6 +83,9 @@ public function span(
             startTime: $startTime,
             endTime: $endTime,
             metadata: $metadata,
+            level: $level,
+            statusMessage: $statusMessage,
+            version: $version,
         );
     }
 
@@ -84,6 +96,8 @@ public function span(
      * @param array<string, mixed>|string $output
      * @param array<string, mixed>|null $modelParameters
      * @param array<string, mixed>|null $metadata
+     * @param array<string, int>|null $usageDetails
+     * @param array<string, float>|null $costDetails
      */
     public function generation(
         string $name,
@@ -97,6 +111,12 @@ public function generation(
         ?array $metadata = null,
         ?string $startTime = null,
         ?string $endTime = null,
+        ?string $completionStartTime = null,
+        ?array $usageDetails = null,
+        ?array $costDetails = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): Generation {
         return $this->ingestion->generation(
             traceId: $this->traceId,
@@ -112,6 +132,12 @@ public function generation(
             metadata: $metadata,
             startTime: $startTime,
             endTime: $endTime,
+            completionStartTime: $completionStartTime,
+            usageDetails: $usageDetails,
+            costDetails: $costDetails,
+            level: $level,
+            statusMessage: $statusMessage,
+            version: $version,
         );
     }
 }

src/Ingestion/Trace.php

@@ -34,6 +34,9 @@ public function update(
         array|string|null $output = null,
         ?array $metadata = null,
         ?array $tags = null,
+        ?string $release = null,
+        ?string $version = null,
+        ?bool $public = null,
     ): self {
         $body = array_filter([
             'id' => $this->traceId,
@@ -44,6 +47,9 @@ public function update(
             'output' => $output,
             'metadata' => $metadata,
             'tags' => $tags,
+            'release' => $release,
+            'version' => $version,
+            'public' => $public,
         ], static fn (mixed $v): bool => $v !== null);
 
         $this->ingestion->send('trace-create', $body);
@@ -66,6 +72,9 @@ public function span(
         ?string $startTime = null,
         ?string $endTime = null,
         ?array $metadata = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): Span {
         return $this->ingestion->span(
             traceId: $this->traceId,
@@ -76,6 +85,9 @@ public function span(
             startTime: $startTime,
             endTime: $endTime,
             metadata: $metadata,
+            level: $level,
+            statusMessage: $statusMessage,
+            version: $version,
         );
     }
 
@@ -86,6 +98,8 @@ public function span(
      * @param array<string, mixed>|string $output
      * @param array<string, mixed>|null $modelParameters
      * @param array<string, mixed>|null $metadata
+     * @param array<string, int>|null $usageDetails
+     * @param array<string, float>|null $costDetails
      */
     public function generation(
         string $name,
@@ -99,6 +113,12 @@ public function generation(
         ?array $metadata = null,
         ?string $startTime = null,
         ?string $endTime = null,
+        ?string $completionStartTime = null,
+        ?array $usageDetails = null,
+        ?array $costDetails = null,
+        ?string $level = null,
+        ?string $statusMessage = null,
+        ?string $version = null,
     ): Generation {
         return $this->ingestion->generation(
             traceId: $this->traceId,
@@ -113,6 +133,12 @@ public function generation(
             metadata: $metadata,
             startTime: $startTime,
             endTime: $endTime,
+            completionStartTime: $completionStartTime,
+            usageDetails: $usageDetails,
+            costDetails: $costDetails,
+            level: $level,
+            statusMessage: $statusMessage,
+            version: $version,
         );
     }
 }

src/Prompt.php

@@ -21,7 +21,8 @@ class Prompt
     public function __construct(
         private readonly TransporterInterface $transporter,
         private readonly string $defaultLabel,
-    ) {}
+    ) {
+    }
 
     /**
      * Retrieve a text prompt by name. Uses default label if no version or label provided.
@@ -49,7 +50,7 @@ public function text(string $promptName, ?int $version = null, ?string $label =
     /**
      * Retrieve a chat prompt by name. Uses default label if no version or label provided.
      *
-     * @param  array<int, array{role: string, content: string}>|null  $fallback
+     * @param array<int, array{role: string, content: string}>|null $fallback
      *
      * @throws InvalidPromptTypeException
      */
@@ -96,10 +97,10 @@ public function list(?string $name = null, ?int $version = null, ?string $label
     /**
      * Create a new prompt.
      *
-     * @param  ($type is PromptType::TEXT ? string : array<int, array{role: string, content: string}>)  $prompt
-     * @param  array<int, string>|null  $labels
-     * @param  array<string, mixed>|null  $config
-     * @param  array<int, string>|null  $tags
+     * @param ($type is PromptType::TEXT ? string : array<int, array{role: string, content: string}>) $prompt
+     * @param array<int, string>|null $labels
+     * @param array<string, mixed>|null $config
+     * @param array<int, string>|null $tags
      * @return ($type is PromptType::TEXT ? TextPromptResponse : ChatPromptResponse)
      *
      * @throws JsonException
@@ -164,7 +165,7 @@ public function create(string $promptName, string|array $prompt, PromptType $typ
     /**
      * Update labels for a specific prompt version.
      *
-     * @param  array<int, string>  $labels
+     * @param array<int, string> $labels
      *
      * @throws JsonException
      */