README

A PHP Client for LangFuse API

This SDK provides a convenient, object‐oriented way to interact with the LangFuse API from your PHP applications. It supports creating and managing traces, spans, generations, events, and scores, and includes integration tests for validation. Test.

Current Implementation (v1.1.0)

• [x] Basic client initialization (keys, host, etc.)
• [x] Tracing service (traces, spans, generations, scores, events)
• [x] Batch (accumulated) sync of traces
• [x] Comprehensive tests (unit and integration)
• [x] SOLID architecture with dependency injection
• [x] Advanced retry logic with circuit breaker patterns
• [x] PHP 8.1+ support
• [x] Strong typing with DTOs and enhanced error handling
• [x] Per-request timeout override capabilities
• [x] User-Agent headers with SDK identification

Installation

Install via Composer:

composer require dropsolid/langfuse-php-sdk

Requirements:
• PHP 8.1+
• GuzzleHTTP

Usage

1. Configure via environment variables or direct constructor args:

   LANGFUSE_PUBLIC_KEY="..."  
   LANGFUSE_SECRET_KEY="..."  
   LANGFUSE_HOST="..."
   

2. Create a client and use the tracing service for all trace operations.

3. Advanced: Per-Sync Timeout Override

   $client = new Client(['timeout' => 20.0]); // Global default
      
   // Quick sync with short timeout
   $client->trace('urgent-operation');
   $client->syncTraces(['timeout' => 5.0]);
      
   // Large batch with extended timeout  
   $client->trace('bulk-operation');
   $client->syncTraces(['timeout' => 60.0]);
   

Roadmap

🎯 v1.1.0 - Quality & Type Safety ✅ COMPLETED

RELEASE NOTES: All v1.1.0 features successfully implemented and tested! This major update transforms the SDK into an enterprise-ready solution with comprehensive type safety, advanced error handling, and flexible configuration options.

Must-Have (Quality Essentials) - ALL COMPLETE:

• [x] Strong Typing & DTOs - Add typed request/response objects for all operations
• [x] Enhanced Error Handling - Specific exception types with detailed context (ApiError, NetworkError, ValidationError)
• [x] User-Agent Headers - Add proper SDK identification headers
• [x] SOLID Architecture - Dependency injection and interface-based design
• [x] PHP 8.1+ Requirement - Upgrade minimum version for better typing support

Should-Have (Configuration Improvements) - ALL COMPLETE:

• [x] Per-Request Timeout Override - Allow custom timeouts per operation
• [x] Retry Configuration - Configurable retry logic with exponential backoff
• [x] Circuit Breaker Pattern - Automatic failure detection with recovery

🚀 Next Features - Core Feature Expansion

Target: Essential missing observability features we plan to work on next

• [ ] Request/Response Logging - Optional debug logging for troubleshooting
• [ ] Session Management - Create and manage user sessions
• [ ] Dataset Support - Basic dataset creation and item management
• [ ] Prompt Management - Create, retrieve, and version prompts
• [ ] Expanded Model Configuration - Enhanced model definitions and management
• [ ] Advanced Filtering - Add filtering options to trace/observation queries
• [ ] Pagination Support - Handle large result sets efficiently

🔮 Backlog - Future Considerations

Features we might consider in the future. Community contributions welcome!

These features are inspired by the Python SDK but may never be implemented depending on demand and priorities. If your company finds any of these critical, please open an issue to help us prioritize, or feel free to submit a PR - it's open source after all!

Performance & Async:

• Async support (ReactPHP/Amp) for non-blocking operations
• Connection pooling and memory optimization
• Background processing and batch size configuration

Advanced Configuration:

• Proxy support and custom middleware
• Compression support for large payloads

Extended Features:

• Media management (upload/manage media files)
• Analytics queries and advanced reporting
• Webhook support for incoming Langfuse events
• Data export in various formats
• Multi-project support in single client

Enterprise Features:

• Health check endpoints and metrics collection
• Custom serialization strategies
• Advanced debugging and monitoring tools