Download the PHP package perfbase/php-sdk without Composer

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

2. Install the Perfbase PHP Extension

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

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

3. Verify Installation

Quick Start

Basic Usage

Advanced Usage with Attributes

Multiple Concurrent Spans

Configuration Options

Basic Configuration

Feature Flags

Control which profiling features are enabled:

Available Feature Flags

API Reference

Core Methods

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

Start profiling a named span with optional initial attributes.

Span names must be 1-64 characters and may only contain letters, numbers, hyphens, and underscores. Empty or whitespace-only names normalize to default.

stopTraceSpan(string $spanName): bool

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

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

Add a custom attribute to the current trace.

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

getTraceData(string $spanName = ''): string

Retrieve the raw Brotli-compressed MessagePack trace payload produced by the extension (useful for debugging or custom processing).

The current extension only supports whole-trace retrieval. Pass the default empty argument; the spanName parameter is kept only for backwards compatibility, and non-empty values are rejected.

reset(): void

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

setFlags(int $flags): void

Change profiling feature flags at runtime.

isExtensionAvailable(): bool

Check if the Perfbase extension is loaded and available.

Static Methods

Perfbase::isAvailable(): bool

Static method to check extension availability without instantiating the class.

Error Handling

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

Best Practices

1. Span Naming

Use descriptive, consistent span names:

Span names may only use letters, numbers, hyphens, and underscores, and must not exceed 64 characters.

2. Attribute Usage

Add meaningful context through attributes:

3. Error Handling in Spans

Always ensure spans are properly closed:

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

5. Forwarded Header Trust

EnvironmentUtils::getUserIp() is a best-effort helper. It reads common proxy/CDN headers when present, but it does not implement a trusted-proxy policy. Only use forwarded-header-derived IPs when your deployment sanitizes those headers at the edge.

Troubleshooting

Extension Not Found

Connection Issues

Debugging

Documentation

Full documentation is available at perfbase.com/docs.

• Docs: perfbase.com/docs
• Issues: github.com/perfbaseorg/php-sdk/issues
• Support: [email protected]

License

Apache-2.0. See LICENSE.txt.