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.

dij-digital / langfuse-laravel

Maintainers

Details