README

This package provides a wrapper around the langfuse-php package, allowing you to easily integrate Langfuse into your Laravel applications. It uses as few dependencies as possible.

Features

• Tracing - Create traces, spans and generations that send directly to the Langfuse API
• Prompts - Fetch, compile and create text and chat prompts with fallback support
• Facade with direct access to prompt() and ingestion() methods

Requires PHP 8.3 or PHP 8.4 in combination with Laravel 11 or Laravel 12

Installation

composer require dij-digital/langfuse-laravel

Configuration

Add the following environment variables to your .env file:

LANGFUSE_BASE_URI=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

# Optional - defaults to config('app.env')
LANGFUSE_ENVIRONMENT=

Publish the config file (optional):

php artisan vendor:publish --tag=langfuse-laravel-config

Usage

Tracing

Every call sends directly to the Langfuse API. No buffering, no flushing.

use DIJ\Langfuse\Laravel\Facades\Langfuse;

// Create a trace
$trace = Langfuse::ingestion()->trace(name: 'handle-request', userId: 'user-1', input: 'hello');

// Nest spans and generations under the trace
$span = $trace->span(name: 'search');
$generation = $span->generation(
    input: 'prompt',
    output: 'response',
    name: 'llm',
    model: 'gpt-4o',
);

// Update any object (sends immediately)
$span->update(output: 'done', endTime: date('c'));
$trace->update(output: 'final answer');

Prompts

use DIJ\Langfuse\Laravel\Facades\Langfuse;

// Get and compile prompts
Langfuse::prompt()->text('promptName', fallback: 'fallback text')->compile(['key' => 'value']);
Langfuse::prompt()->chat('chatName', fallback: [['role' => 'user', 'content' => 'fallback']])->compile(['key' => 'value']);

// List all prompts (auto-paginated Generator)
foreach (Langfuse::prompt()->list() as $item) {
    echo $item->name;
}

// Create a prompt
Langfuse::prompt()->create('promptName', 'text', PromptType::TEXT);

// Update prompt labels
Langfuse::prompt()->update(promptName: 'promptName', version: 1, labels: ['production']);

Testing

Use the fake() method to mock HTTP responses. The langfuse-php package ships with testing response helpers that provide sensible defaults — just override the fields you care about:

use DIJ\Langfuse\Laravel\Facades\Langfuse;
use DIJ\Langfuse\PHP\Testing\Responses\GetPromptResponse;

Langfuse::fake([
    new GetPromptResponse(data: [
        'name' => 'my-prompt',
        'type' => 'text',
        'prompt' => 'Hello {{name}}',
    ]),
]);

$prompt = Langfuse::prompt()->text('my-prompt');

Available test response helpers in DIJ\Langfuse\PHP\Testing\Responses:

• GetPromptResponse — text prompt fetch
• GetChatPromptResponse — chat prompt fetch
• NoPromptFoundResponse — 404 prompt not found
• PostPromptResponse — text prompt creation
• PostChatPromptResponse — chat prompt creation
• PatchPromptLabelsResponse — prompt label update
• GetPromptListPageOneResponse — first page of prompt list
• GetPromptListPageTwoResponse — second page of prompt list

Responses are consumed sequentially (Guzzle MockHandler), so the order of responses must match the order of HTTP calls your code makes.

Development

composer test        # Run tests
composer codestyle   # Format, refactor and analyse

Ingestion

use DIJ\Langfuse\Laravel\Facades\Langfuse;

// Creates a trace and a generation visible in Langfuse UI
$traceId = 'trace-id-123';

Langfuse::ingestion()->trace(
    input: 'prompt text',
    output: null,
    traceId: $traceId,
    name: 'name',
    sessionId: null,
    metadata: ['key' => 'value']
);

Langfuse::ingestion()->generation(
    input: 'prompt text',
    output: 'model output',
    traceId: $traceId,
    name: 'name',
    sessionId: null,
    promptName: 'promptName',
    promptVersion: 1,
    model: 'gpt-4o',
    modelParameters: ['temperature' => 0.7],
    metadata: ['key' => 'value']
);

Langfuse Laravel was created by Tycho Engberink and is maintained by DIJ Digital under the MIT license.