README

Perfbase PHP SDK

The official PHP SDK for Perfbase — application performance monitoring and profiling for PHP applications.

Using a PHP framework?

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

Laravel: perfbase/laravel
Symfony: perfbase/symfony
WordPress: perfbase/wordpress
CakePHP: perfbase/cakephp
Drupal: perfbase/drupal
Slim: perfbase/slim
Joomla: perfbase/joomla
CodeIgniter 4: perfbase/codeigniter4
Yii 1.1: perfbase/yii1
Yii 2: perfbase/yii2
Yii 3: perfbase/yii3

If you're not using a framework or need a custom integration, this SDK is 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.5
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:^1.0

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://ingress.perfbase.cloud', // 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
$result = $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', (string) 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
$result = $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
$result = $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(): SubmitResult`

Submit collected profiling data to Perfbase. Resets the session on success; preserves trace state on failure so callers can decide whether to retry or discard.

The SDK sends the exact raw bytes returned by perfbase_get_data() as the request body. It adds the payload encoding version and client-created timestamp as HTTP headers; it does not JSON-wrap or base64-encode the trace payload.

The returned SubmitResult provides:

isSuccess(): bool — delivery confirmed
isRetryable(): bool — transient failure (network error, 429, 5xx)
isPermanentFailure(): bool — non-retryable (401, 403, 400, etc.)
getStatusCode(): ?int — HTTP status code if a response was received
getMessage(): string — human-readable description

$result = $perfbase->submitTrace();

if (!$result->isSuccess()) {
    // Handle failure — trace state is preserved for retry
    error_log("Trace submission failed: " . $result->getMessage());
}

`getTraceData(string $spanName = ''): string`

Retrieve the raw Brotli-compressed MessagePack trace payload produced by the extension (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
}

// Submission failures are returned as SubmitResult, not thrown
$result = $perfbase->submitTrace();
if ($result->isRetryable()) {
    // Transient failure — safe to retry later
} elseif ($result->isPermanentFailure()) {
    // Non-retryable — check API key, payload, etc.
    error_log("Permanent submission failure: " . $result->getMessage());
}

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', (string) count($results));
$perfbase->setAttribute('query_time_ms', (string) $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

Full documentation is available at perfbase.com/docs.

Docs: perfbase.com/docs
Issues: github.com/perfbaseorg/php-sdk/issues
Support: support@perfbase.com

License

Apache-2.0. See LICENSE.txt.

perfbase / php-sdk

Maintainers

Package info

Statistics

Security