WordPress Integration

The Perfbase WordPress plugin provides automatic performance monitoring for WordPress sites, including WooCommerce. Requires PHP 7.4+ and WordPress 5.0+.

Installation

Install the Perfbase PHP extension first. This is what does the actual profiling:

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

Install the plugin via Composer (recommended for Bedrock-style installs):

composer require perfbase/wordpress

Or install manually by copying the plugin to wp-content/plugins/perfbase and running composer install --no-dev inside the plugin directory.

Activate the plugin in Plugins in the WordPress admin.

Configuration

Configure via Settings > Perfbase in the admin panel. All settings can also be overridden with constants in wp-config.php, and constants take priority over the admin UI.

// wp-config.php
define('PERFBASE_API_KEY', 'your-api-key');
define('PERFBASE_ENABLED', true);

Constants

Constant	Default	Description
`PERFBASE_ENABLED`	`false`	Master on/off switch.
`PERFBASE_API_KEY`	`''`	Your project API key. Required.
`PERFBASE_SAMPLE_RATE`	`0.1`	Fraction of requests to profile (0.0–1.0). `0.1` = 10%.
`PERFBASE_API_URL`	`https://ingress.perfbase.cloud`	Ingestion endpoint.
`PERFBASE_TIMEOUT`	`10`	HTTP timeout in seconds for trace submission.
`PERFBASE_PROXY`	-	Optional proxy URL.
`PERFBASE_FLAGS`	`DefaultFlags`	SDK feature flags bitmask. See Feature flags.
`PERFBASE_DEBUG`	`false`	Throw profiling errors instead of silently logging them.
`PERFBASE_LOG_ERRORS`	`true`	Log profiling errors via `error_log()`.
`PERFBASE_ENVIRONMENT`	auto-detected	Environment name. Falls back to `wp_get_environment_type()`, then `WP_DEBUG`.
`PERFBASE_APP_VERSION`	WordPress version	Application version recorded on traces.

Context toggles

Control which types of requests are profiled. These are configured in the admin UI:

Setting	Default	Description
Profile Admin Area	Off	Profile `wp-admin` requests.
Profile AJAX Requests	On	Profile WordPress AJAX requests (`admin-ajax.php`).
Profile Cron Jobs	On	Profile WordPress cron executions.
Profile WP-CLI Commands	Off	Profile WP-CLI commands.

Include and exclude filters

Control which paths are profiled with include/exclude patterns, configured in the admin UI under Exclusions (one pattern per line):

Default excludes: /wp-content/uploads/*, /favicon.ico

Default user agent excludes: bot, crawler, spider (case-insensitive substring match)

Pattern types

Glob patterns: /api/*, /wp-admin/edit.php (matched via fnmatch())
Regex patterns: /^POST \/wp-json\// (wrapped in forward slashes)
Catch-all: * matches everything

Patterns are tested against both the request path and {METHOD} {path} (e.g., GET /my-page).

What gets profiled

The plugin hooks into WordPress lifecycle events automatically. No code changes required.

WordPress lifecycle

Theme setup and plugin load phases
wp_head and wp_footer milestones
Database query count, slow queries (>100ms), and total query time (requires SAVEQUERIES)
Memory usage (peak and current)
Active plugin count

Content events

Post creation and updates (with post type)
Comment insertion
User login and logout

REST API

Route and HTTP method recorded when a REST API request is detected

Outbound HTTP

External HTTP request URLs are tracked (scheme + host + path only, no query parameters)

WooCommerce

If WooCommerce is active, the plugin additionally tracks:

WooCommerce version
Current page type (shop, product, cart, checkout, account)
Product ID and type on product pages
Cart additions with quantity
New order creation

Automatic attributes

Every trace includes these attributes automatically:

Attribute	Source
`action`	`{METHOD} {path}` (no query string)
`hostname`	`gethostname()`
`environment`	`wp_get_environment_type()` or `PERFBASE_ENVIRONMENT`
`app_version`	`PERFBASE_APP_VERSION` or WordPress version
`php_version`	PHP version
`wordpress.version`	WordPress version
`http_method`	Request method
`http_url`	Full URL without query string
`http_status_code`	Response status code
`user_ip`	Client IP (checks CF-Connecting-IP, X-Forwarded-For, etc.)
`user_agent`	User agent string
`user_id`	WordPress user ID (if logged in)

WordPress-specific attributes use dot notation (wordpress.version, woocommerce.page). Core trace fields use underscores (http_method, http_status_code).

Sample rate

The sample rate controls what fraction of requests are profiled:

define('PERFBASE_SAMPLE_RATE', 1.0);   // Profile everything (development)
define('PERFBASE_SAMPLE_RATE', 0.1);   // 10% of requests (production)
define('PERFBASE_SAMPLE_RATE', 0.01);  // 1% of requests (high-traffic)

When a request isn’t sampled, no profiling overhead is incurred.

Error handling

Profiling never crashes your site. In production, all profiling errors are caught and optionally logged via error_log(). With PERFBASE_DEBUG enabled, errors are thrown so you can catch configuration issues during development.

If the Perfbase PHP extension is not installed, the plugin detects this gracefully and simply does not profile. A warning is shown on the settings page.

Admin settings page

The settings page at Settings > Perfbase provides:

API key and profiling toggle
Sample rate configuration
Advanced options (API URL, timeout, proxy)
Context toggles (admin, AJAX, cron, CLI)
Feature flag checkboxes
Include/exclude path patterns
User agent exclusions
System information: shows plugin version, PHP version, extension availability, and current profiling status

Uninstalling

Deactivating the plugin stops all profiling immediately. Uninstalling (deleting) the plugin removes all saved settings from the database.

← Symfony Integration CakePHP Integration →