langfuse/php-client

PHP Client for Langfuse API

dev-main 2025-11-03 11:18 UTC

Requires

• php: >=8.3
• ext-json: *
• php-http/discovery: ^1.20
• psr/http-client: ^1.0
• psr/http-factory: ^1.1
• psr/http-message: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• nyholm/psr7: ^1.8
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• squizlabs/php_codesniffer: ^4.0
• symfony/http-client: ^7.3
• symfony/var-dumper: ^7.3

MIT

• Franz Mayr-Wilding

README

Alles klar — wir passen das README auf den neuen Stil mit Gettern an ($client->trace() statt $client->trace). Ich aktualisiere alle Beispiele, Tabellen & Text.

🚀 What is Langfuse?

Langfuse is an open-source LLM engineering platform designed for:

• Tracing and logging LLM application behavior
• Managing prompts and versioning
• Experimentation and evaluation
• Scoring, feedback, and monitoring

This package is an unofficial PHP SDK offering a structured interface to the Langfuse Public API.

📦 Installation

composer require langfuse/php-client

🔑 Authentication

You will need:

Key	Where to get it
Public Key	Langfuse Dashboard → Project Settings → API Keys
Secret Key	Langfuse Dashboard → Project Settings → API Keys

🧱 Basic Usage

use Langfuse\Client;

$client = new Client(
    publicKey: 'YOUR_PUBLIC_KEY',
    secretKey: 'YOUR_SECRET_KEY',
);

This will use:

• Default Base URL: https://cloud.langfuse.com/api/public
• Auto-discovered PSR-18 HTTP client and PSR-17 factories

✨ Example: Create a Trace

use Langfuse\Client;
use Langfuse\DTO\Trace\CreateTraceDTO;

$client = new Client('YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY');

$trace = $client->trace()->create(new CreateTraceDTO(
    name: 'example-trace',
    input: 'User input...',
    output: 'Model response...'
));

echo $trace->id;

💡 Using in Laravel

1. Add environment variables

LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key

2. Register a Service Provider Singleton

// app/Providers/LangfuseServiceProvider.php

use Illuminate\Support\ServiceProvider;
use Langfuse\Client;

class LangfuseServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(Client::class, function () {
            return new Client(
                publicKey: config('services.langfuse.public_key'),
                secretKey: config('services.langfuse.secret_key'),
            );
        });
    }
}

3. Add to config/services.php

'langfuse' => [
    'public_key' => env('LANGFUSE_PUBLIC_KEY'),
    'secret_key' => env('LANGFUSE_SECRET_KEY'),
],

4. Use it anywhere:

use Langfuse\Client;
use Langfuse\DTO\Trace\CreateTraceDTO;

class ChatController extends Controller
{
    public function handle(Client $langfuse)
    {
        $response = "AI response...";

        $langfuse->trace()->create(new CreateTraceDTO(
            name: 'chat-session',
            input: request('message'),
            output: $response,
        ));

        return $response;
    }
}

💡 Using in Symfony

1. Add environment variables

LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key

2. Register the Client as a service

# config/services.yaml
services:
  Langfuse\Client:
    arguments:
      $publicKey: '%env(LANGFUSE_PUBLIC_KEY)%'
      $secretKey: '%env(LANGFUSE_SECRET_KEY)%'

3. Use in a Controller

use Langfuse\Client;
use Langfuse\DTO\Trace\CreateTraceDTO;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class ChatController extends AbstractController
{
    public function __invoke(Client $client)
    {
        $trace = $client->trace()->create(new CreateTraceDTO(
            name: 'symfony-chat',
            input: 'User says hello',
            output: 'Bot replies hi',
        ));

        return $this->json(['trace_id' => $trace->id]);
    }
}

🧩 Custom Base URL (Self-Hosted)

$client = new Client(
    publicKey: 'PUBLIC_KEY',
    secretKey: 'SECRET_KEY',
    baseUrl: 'https://your-langfuse-instance/api/public'
);

📚 Available API Endpoints

Getter	Description
$client->annotationQueue()	Manage annotation queues
$client->annotation()	Create/list annotations
$client->dataset()	Create & manage datasets
$client->datasetItem()	Manage dataset items
$client->evaluation()	Run or fetch evaluations
$client->experiment()	Structured model experiments
$client->generation()	Log LLM generations
$client->observation()	Log observation events
$client->prompt()	Create & version prompts
$client->project()	Project configuration
$client->score()	Submit feedback & metrics
$client->trace()	Record high-level traces

🛠️ Requirements

• PHP 8.0+
• A PSR-18 HTTP Client (e.g., Guzzle, Symfony HTTP Client)
• PSR-17 Factories (auto-discovered via php-http/discovery)

🤝 Contributing

Pull Requests and Issues welcome!

📄 License

MIT — feel free to use, modify, distribute.