Perfbase PHP SDK

A comprehensive PHP SDK for application performance monitoring (APM) and profiling with Perfbase. This SDK provides real-time performance insights, distributed tracing, and detailed profiling capabilities for PHP applications.

Important: Using a PHP Framework?

If you're using a PHP framework, we highly recommend using our dedicated framework integrations for the best experience:

• Laravel: Use perfbase/laravel for automatic integration with Laravel applications
• Symfony: Coming soon
• Other frameworks: This SDK provides the foundation for custom integrations

If you're NOT using a framework or need custom integration - this is the SDK for you!

Features

• 🚀 Real-time Performance Profiling - CPU time, memory usage, and execution tracing
• 📊 Multi-span Tracing - Track multiple concurrent operations within a single request
• 🔍 Database Query Tracking - Monitor PDO, MongoDB, Elasticsearch queries
• 🌐 HTTP Request Monitoring - Track outbound HTTP calls and API requests
• 💾 Cache Operation Tracking - Monitor Redis, Memcached, and other cache operations
• ⚡ Queue System Monitoring - Track background job performance
• 🏷️ Custom Attributes - Add contextual metadata to your traces
• 🔧 Configurable Feature Flags - Enable/disable specific profiling features
• 🛡️ Multi-tenant Support - Organization and project-level data isolation

Requirements

• PHP: 7.4 to 8.4
• Operating System: Linux or macOS (Windows not supported)
• Dependencies:
  • ext-curl (usually enabled by default)
  • ext-perfbase (Perfbase PHP extension)
• Package Manager: Composer

Installation

1. Install the SDK

composer require perfbase/php-sdk

2. Install the Perfbase PHP Extension

The ext-perfbase PHP extension is required for the SDK to function. Install it using:

bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

Important: Restart your web server or PHP-FPM service after installation.

3. Verify Installation

<?php
use Perfbase\SDK\Perfbase;

// Check if the extension is available
if (Perfbase::isAvailable()) {
    echo "Perfbase extension is ready!";
} else {
    echo "Perfbase extension not found. Please install ext-perfbase.";
}

Quick Start

Basic Usage

<?php
use Perfbase\SDK\Perfbase;
use Perfbase\SDK\Config;

// Create configuration
$config = Config::fromArray([
    'api_key' => 'your_api_key_here',
    'api_url' => 'https://receiver.perfbase.com', // Optional: defaults to this URL
]);

// Initialize Perfbase
$perfbase = new Perfbase($config);

// Start profiling a span
$perfbase->startTraceSpan('user_registration');

// Your application code here
registerUser($userData);

// Stop the span
$perfbase->stopTraceSpan('user_registration');

// Submit the trace data to Perfbase
$perfbase->submitTrace();

Advanced Usage with Attributes

<?php
use Perfbase\SDK\Perfbase;
use Perfbase\SDK\Config;
use Perfbase\SDK\FeatureFlags;

// Configure with custom settings
$config = Config::fromArray([
    'api_key' => 'your_api_key_here',
    'timeout' => 15,
    'flags' => FeatureFlags::AllFlags, // Enable all profiling features
]);

$perfbase = new Perfbase($config);

// Start span with initial attributes
$perfbase->startTraceSpan('api_request', [
    'endpoint' => '/api/v1/users',
    'method' => 'POST',
    'user_id' => '12345'
]);

// Add attributes during execution
$perfbase->setAttribute('request_size', '1024');
$perfbase->setAttribute('cache_hit', 'false');

try {
    // Your application logic
    $result = processApiRequest($request);
    
    $perfbase->setAttribute('status', 'success');
    $perfbase->setAttribute('response_size', strlen($result));
    
} catch (Exception $e) {
    $perfbase->setAttribute('status', 'error');
    $perfbase->setAttribute('error_message', $e->getMessage());
} finally {
    // Always stop the span
    $perfbase->stopTraceSpan('api_request');
}

// Submit trace data
$perfbase->submitTrace();

Multiple Concurrent Spans

<?php
$perfbase = new Perfbase($config);

// Start multiple spans for different operations
$perfbase->startTraceSpan('database_operations');
$perfbase->startTraceSpan('cache_operations');
$perfbase->startTraceSpan('api_calls');

// Perform operations (can be in any order)
performDatabaseQuery();
$perfbase->stopTraceSpan('database_operations');

makeApiCall();
$perfbase->stopTraceSpan('api_calls');

accessCache();
$perfbase->stopTraceSpan('cache_operations');

// Submit all trace data
$perfbase->submitTrace();

Configuration Options

Basic Configuration

$config = Config::fromArray([
    'api_key' => 'required_api_key',           // Your Perfbase API key
    'api_url' => 'https://custom.endpoint',    // Custom API endpoint (optional)
    'timeout' => 10,                           // Request timeout in seconds (default: 10)
    'proxy' => 'http://proxy.example.com:8080' // Proxy server (optional)
]);

Feature Flags

Control which profiling features are enabled:

use Perfbase\SDK\FeatureFlags;

// Use default flags (recommended for most applications)
$config = Config::fromArray([
    'api_key' => 'your_api_key',
    'flags' => FeatureFlags::DefaultFlags
]);

// Enable all available features
$config = Config::fromArray([
    'api_key' => 'your_api_key',
    'flags' => FeatureFlags::AllFlags
]);

// Custom combination
$customFlags = FeatureFlags::TrackCpuTime | 
               FeatureFlags::TrackPdo | 
               FeatureFlags::TrackHttp;

$config = Config::fromArray([
    'api_key' => 'your_api_key',
    'flags' => $customFlags
]);

// Change flags at runtime
$perfbase->setFlags(FeatureFlags::TrackCpuTime | FeatureFlags::TrackMemoryAllocation);

Available Feature Flags

Flag	Description
UseCoarseClock	Faster, less accurate timing (reduces overhead)
TrackCpuTime	Monitor CPU time usage
TrackMemoryAllocation	Track memory allocation patterns
TrackPdo	Monitor database queries via PDO
TrackHttp	Track outbound HTTP requests
TrackCaches	Monitor cache operations (Redis, Memcached)
TrackMongodb	Track MongoDB operations
TrackElasticsearch	Monitor Elasticsearch queries
TrackQueues	Track queue/background job operations
TrackAwsSdk	Monitor AWS SDK operations
TrackFileOperations	Track file I/O operations
TrackFileCompilation	Monitor PHP file compilation
TrackFileDefinitions	Track PHP class/function definitions
TrackExceptions	Monitor exception handling

API Reference

Core Methods

startTraceSpan(string $spanName, array $attributes = []): void

Start profiling a named span with optional initial attributes.

$perfbase->startTraceSpan('user_login', [
    'user_id' => '123',
    'login_method' => 'oauth'
]);

stopTraceSpan(string $spanName): bool

Stop profiling a named span. Returns true if successful, false if span wasn't active.

$success = $perfbase->stopTraceSpan('user_login');

setAttribute(string $key, string $value): void

Add a custom attribute to the current trace.

$perfbase->setAttribute('cache_hit_ratio', '0.85');

submitTrace(): void

Submit collected profiling data to Perfbase and reset the session.

$perfbase->submitTrace();

getTraceData(string $spanName = ''): string

Retrieve raw trace data (useful for debugging or custom processing).

$rawData = $perfbase->getTraceData();

reset(): void

Clear all active spans and reset the profiling session without submitting.

$perfbase->reset();

setFlags(int $flags): void

Change profiling feature flags at runtime.

$perfbase->setFlags(FeatureFlags::TrackCpuTime | FeatureFlags::TrackPdo);

isExtensionAvailable(): bool

Check if the Perfbase extension is loaded and available.

if ($perfbase->isExtensionAvailable()) {
    // Extension is ready
}

Static Methods

Perfbase::isAvailable(): bool

Static method to check extension availability without instantiating the class.

if (Perfbase::isAvailable()) {
    $perfbase = new Perfbase($config);
}

Error Handling

The SDK is designed to fail gracefully when the extension is not available:

use Perfbase\SDK\Exception\PerfbaseExtensionException;

try {
    $perfbase = new Perfbase($config);
} catch (PerfbaseExtensionException $e) {
    // Extension not available - handle gracefully
    error_log("Perfbase extension not available: " . $e->getMessage());
    // Your application continues normally
}

Best Practices

1. Span Naming

Use descriptive, consistent span names:

// Good
$perfbase->startTraceSpan('user_authentication');
$perfbase->startTraceSpan('database_user_lookup');
$perfbase->startTraceSpan('external_api_call');

// Avoid
$perfbase->startTraceSpan('function1');
$perfbase->startTraceSpan('temp_span');

2. Attribute Usage

Add meaningful context through attributes:

$perfbase->startTraceSpan('database_query', [
    'table' => 'users',
    'operation' => 'SELECT',
    'rows_expected' => '1'
]);

$perfbase->setAttribute('rows_returned', count($results));
$perfbase->setAttribute('query_time_ms', $executionTime);

3. Error Handling in Spans

Always ensure spans are properly closed:

$perfbase->startTraceSpan('risky_operation');

try {
    performRiskyOperation();
    $perfbase->setAttribute('status', 'success');
} catch (Exception $e) {
    $perfbase->setAttribute('status', 'error');
    $perfbase->setAttribute('error_type', get_class($e));
    throw $e; // Re-throw if needed
} finally {
    $perfbase->stopTraceSpan('risky_operation');
}

4. Performance Considerations

• Use FeatureFlags::UseCoarseClock for high-throughput applications
• Only enable the tracking features you need
• Consider the overhead of frequent setAttribute() calls in tight loops

Troubleshooting

Extension Not Found

# Check if extension is loaded
php -m | grep perfbase

# Check PHP configuration
php --ini

# Reinstall extension
bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

Connection Issues

// Test connectivity
$config = Config::fromArray([
    'api_key' => 'your_api_key',
    'timeout' => 30 // Increase timeout for testing
]);

Debugging

// Get raw trace data for inspection
$traceData = $perfbase->getTraceData();
var_dump($traceData);

// Check extension status
var_dump(Perfbase::isAvailable());

Documentation

Comprehensive documentation is available at https://docs.perfbase.com, including:

• Data handling policies and security measures
• Legal information and compliance
• Detailed information about data collection and storage
• Advanced configuration options
• Integration guides for various frameworks

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support

• Email: support@perfbase.com
• Documentation: https://docs.perfbase.com
• Issues: GitHub Issues

Contributing

We welcome contributions! Please see our contributing guidelines and feel free to submit pull requests.

---

Note: This SDK requires the ext-perfbase PHP extension. Without it, the SDK will throw a PerfbaseExtensionException during initialization. The extension is currently available for Linux and macOS only.