DIJ-digital · tychoengberinkDIJ · Jan 22, 2026 · Feb 20, 2026
diff --git a/composer.json b/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",

diff --git a/src/Contracts/TransporterInterface.php b/src/Contracts/TransporterInterface.php
@@ -9,34 +9,34 @@
 interface TransporterInterface
 {
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function request(string $method, string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function get(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function post(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function postJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function delete(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function patchJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 }
diff --git a/src/Langfuse.php b/src/Langfuse.php
@@ -12,7 +12,13 @@ public function __construct(
         private readonly TransporterInterface $transporter,
         private readonly string $environment = 'default',
         private readonly string $label = 'latest',
-    ) {
+    ) {}
+
+    public function media(): Media
+    {
+        return new Media(
+            transporter: $this->transporter,
+        );
     }
 
     public function prompt(): Prompt

diff --git a/src/Media.php b/src/Media.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP;
+
+use DIJ\Langfuse\PHP\Contracts\TransporterInterface;
+use DIJ\Langfuse\PHP\Responses\MediaResponse;
+use DIJ\Langfuse\PHP\Responses\MediaUploadUrlResponse;
+use JsonException;
+
+class Media
+{
+    public function __construct(private readonly TransporterInterface $transporter) {}
+
+    /**
+     * @throws JsonException
+     */
+    public function get(string $mediaId): MediaResponse
+    {
+        $response = $this->transporter->get(
+            uri: sprintf('/api/public/media/%s', urlencode($mediaId)),
+        );
+
+        /** @var array{
+         *     mediaId: string,
+         *     contentType: string,
+         *     contentLength: int,
+         *     uploadedAt: string,
+         *     url: string,
+         *     urlExpiry: string
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return MediaResponse::fromArray($data);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function getUploadUrl(
+        string $traceId,
+        string $contentType,
+        int $contentLength,
+        string $sha256Hash,
+        string $field,
+        ?string $observationId = null,
+    ): MediaUploadUrlResponse {
+        $response = $this->transporter->postJson(
+            uri: '/api/public/media',
+            data: array_filter([
+                'traceId' => $traceId,
+                'observationId' => $observationId,
+                'contentType' => $contentType,
+                'contentLength' => $contentLength,
+                'sha256Hash' => $sha256Hash,
+                'field' => $field,
+            ], fn ($v) => $v !== null),
+        );
+
+        /** @var array{
+         *     uploadUrl: string|null,
+         *     mediaId: string
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return MediaUploadUrlResponse::fromArray($data);
+    }
+
+    public function patch(
+        string $mediaId,
+        string $uploadedAt,
+        int $uploadHttpStatus,
+        ?string $uploadHttpError = null,
+        ?int $uploadTimeMs = null,
+    ): void {
+        $this->transporter->patchJson(
+            uri: sprintf('/api/public/media/%s', urlencode($mediaId)),
+            data: array_filter([
+                'uploadedAt' => $uploadedAt,
+                'uploadHttpStatus' => $uploadHttpStatus,
+                'uploadHttpError' => $uploadHttpError,
+                'uploadTimeMs' => $uploadTimeMs,
+            ], fn ($v) => $v !== null),
+        );
+    }
+}
diff --git a/src/Responses/MediaResponse.php b/src/Responses/MediaResponse.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class MediaResponse
+{
+    public function __construct(
+        public string $mediaId,
+        public string $contentType,
+        public int $contentLength,
+        public string $uploadedAt,
+        public string $url,
+        public string $urlExpiry,
+    ) {}
+
+    /**
+     * @param array{
+     *     mediaId: string,
+     *     contentType: string,
+     *     contentLength: int,
+     *     uploadedAt: string,
+     *     url: string,
+     *     urlExpiry: string
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            mediaId: $data['mediaId'],
+            contentType: $data['contentType'],
+            contentLength: $data['contentLength'],
+            uploadedAt: $data['uploadedAt'],
+            url: $data['url'],
+            urlExpiry: $data['urlExpiry'],
+        );
+    }
+}
diff --git a/src/Responses/MediaUploadUrlResponse.php b/src/Responses/MediaUploadUrlResponse.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class MediaUploadUrlResponse
+{
+    public function __construct(
+        public string $mediaId,
+        public ?string $uploadUrl,
+    ) {}
+
+    /**
+     * @param array{
+     *     uploadUrl: string|null,
+     *     mediaId: string
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            mediaId: $data['mediaId'],
+            uploadUrl: $data['uploadUrl'],
+        );
+    }
+}
diff --git a/src/Testing/Responses/GetMediaResponse.php b/src/Testing/Responses/GetMediaResponse.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetMediaResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     * @param  array<string, mixed>  $data
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null, array $data = [])
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload($data)), $version, $reason);
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function payload(array $data = []): array
+    {
+        return array_merge([
+            'mediaId' => 'media-abc123',
+            'contentType' => 'image/png',
+            'contentLength' => 12345,
+            'uploadedAt' => '2025-01-22T10:00:00.000Z',
+            'url' => 'https://storage.langfuse.com/media/abc123.png',
+            'urlExpiry' => '2025-01-22T11:00:00.000Z',
+        ], $data);
+    }
+}
diff --git a/src/Testing/Responses/PatchMediaResponse.php b/src/Testing/Responses/PatchMediaResponse.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class PatchMediaResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     */
+    public function __construct(int $status = 204, array $headers = [], string $version = '1.1', ?string $reason = null)
+    {
+        parent::__construct($status, $headers, '', $version, $reason);
+    }
+}
diff --git a/src/Testing/Responses/PostMediaUploadUrlResponse.php b/src/Testing/Responses/PostMediaUploadUrlResponse.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class PostMediaUploadUrlResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     * @param  array<string, mixed>  $data
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null, array $data = [])
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload($data)), $version, $reason);
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function payload(array $data = []): array
+    {
+        return array_merge([
+            'mediaId' => 'media-new123',
+            'uploadUrl' => 'https://storage.langfuse.com/upload/presigned-url',
+        ], $data);
+    }
+}
diff --git a/src/Transporters/HttpTransporter.php b/src/Transporters/HttpTransporter.php
@@ -21,8 +21,7 @@ class HttpTransporter implements TransporterInterface
 {
     public function __construct(
         public readonly ClientInterface $client
-    ) {
-    }
+    ) {}
 
     /**
      * @throws BadRequestException
@@ -45,7 +44,7 @@ public function request(string $method, string $uri, array $options = []): Respo
     }
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      *
      * @throws BadRequestException
      * @throws ForbiddenException
@@ -61,7 +60,7 @@ public function get(string $uri, array $options = []): ResponseInterface
     }
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      *
      * @throws BadRequestException
      * @throws ForbiddenException
@@ -82,7 +81,7 @@ public function postJson(string $uri, array $data = [], array $options = []): Re
     }
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      *
      * @throws BadRequestException
      * @throws ForbiddenException
@@ -98,8 +97,8 @@ public function delete(string $uri, array $options = []): ResponseInterface
     }
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      *
      * @throws BadRequestException
      * @throws ForbiddenException