PHPackages                             perfbase/wordpress - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. perfbase/wordpress

ActiveWordpress-plugin[Logging & Monitoring](/categories/logging)

perfbase/wordpress
==================

WordPress integration for the Perfbase APM platform

v1.5.2(2w ago)114↓100%GPL-2.0-or-laterPHPPHP >=7.4 <8.5CI passing

Since Apr 8Pushed 2w agoCompare

[ Source](https://github.com/perfbaseorg/wordpress)[ Packagist](https://packagist.org/packages/perfbase/wordpress)[ Docs](https://github.com/perfbaseorg/wordpress)[ RSS](/packages/perfbase-wordpress/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (7)Versions (18)Used By (0)

 [ ![Perfbase](https://camo.githubusercontent.com/a4e071fd1246cf5c68819015801139400d74b208b76a07ba8c5945d6e4ffd3ba/68747470733a2f2f63646e2e70657266626173652e636f6d2f696d672f6c6f676f2d66756c6c2e737667) ](https://perfbase.com)

### Perfbase for WordPress

[](#perfbase-for-wordpress)

 WordPress integration for [Perfbase](https://perfbase.com).

 [![Packagist Version](https://camo.githubusercontent.com/f3c019dce51009cc88649369bc61bd67721b5ea3d37b963043959e75f269a1fd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70657266626173652f776f72647072657373)](https://packagist.org/packages/perfbase/wordpress) [![License](https://camo.githubusercontent.com/e1bf092edccb0d78bb00b86bc80f10aa3a41eb86cb02c32e06fcf44513d3f74d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f70657266626173652f776f72647072657373)](https://github.com/perfbaseorg/wordpress/blob/main/LICENSE.txt) [![CI](https://camo.githubusercontent.com/f32ca70abf9c6b1d6207acde38bedc705b2d53b5564ce5c1a5ca156a49a841dc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70657266626173656f72672f776f726470726573732f74657374732e796d6c3f6272616e63683d6d61696e)](https://github.com/perfbaseorg/wordpress/actions/workflows/tests.yml) [![PHP Version](https://camo.githubusercontent.com/1150142271e92a6b30ce3ef37f5548f25d15d1e9cd200eea972f746cc7a2c40a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e342532422d626c7565)](https://camo.githubusercontent.com/1150142271e92a6b30ce3ef37f5548f25d15d1e9cd200eea972f746cc7a2c40a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e342532422d626c7565) [![WordPress Version](https://camo.githubusercontent.com/4cbecf656284a7d00b38b2fcedc0a8096b2a3eb2ae93f11ab5c9c6c4b3e1a917/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f776f726470726573732d352e302532422d626c7565)](https://camo.githubusercontent.com/4cbecf656284a7d00b38b2fcedc0a8096b2a3eb2ae93f11ab5c9c6c4b3e1a917/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f776f726470726573732d352e302532422d626c7565)

This plugin is a thin adapter over [`perfbase/php-sdk`](https://packagist.org/packages/perfbase/php-sdk). It detects the current WordPress execution context, starts and stops trace spans through the shared SDK, and adds WordPress-specific metadata along the way.

What it profiles
----------------

[](#what-it-profiles)

- Standard HTTP requests
- WordPress admin requests when enabled
- AJAX requests
- WordPress cron runs
- WP-CLI commands
- Additional WordPress metadata through hook-based attribute collection

Requirements
------------

[](#requirements)

- PHP `>=7.4  Perfbase`
3. Add your Perfbase API key
4. Enable profiling
5. Start with a sample rate like `0.1`

If you prefer configuration in code, define the supported constants in `wp-config.php`:

```
define('PERFBASE_ENABLED', true);
define('PERFBASE_API_KEY', 'your-api-key-here');
define('PERFBASE_SAMPLE_RATE', 0.1);
define('PERFBASE_API_URL', 'https://ingress.perfbase.cloud');
define('PERFBASE_TIMEOUT', 10);
define('PERFBASE_PROXY', '');
define('PERFBASE_FLAGS', \Perfbase\SDK\FeatureFlags::DefaultFlags);
define('PERFBASE_PROFILE_HTTP_STATUS_CODES', '200-299,500-599');
define('PERFBASE_DEBUG', false);
define('PERFBASE_LOG_ERRORS', true);

// Trace metadata helpers
define('PERFBASE_ENVIRONMENT', 'production');
define('PERFBASE_APP_VERSION', '1.0.0');
```

Configuration model
-------------------

[](#configuration-model)

Configuration priority is:

1. Defaults from `ConfigManager`
2. Saved WordPress options (`perfbase_settings`)
3. `wp-config.php` constants for the supported core keys

### Core settings

[](#core-settings)

SettingDefaultPurpose`enabled``false`Global on/off switch`debug``false`Surface profiling failures instead of failing open`log_errors``true`Log profiling failures when debug is off`api_key``''`Perfbase API key`api_url``https://ingress.perfbase.cloud`Receiver base URL`sample_rate``0.1`Sampling rate between `0.0` and `1.0``timeout``10`Submission timeout in seconds`proxy``''`Optional outbound proxy`flags``FeatureFlags::DefaultFlags`Perfbase extension flags`profile_http_status_codes``array_merge(range(200, 299), range(500, 599))`HTTP response codes that should be submitted### Context toggles

[](#context-toggles)

SettingDefaultNotes`profile_admin``false`Skip admin by default`profile_ajax``true`AJAX requests are profiled by default`profile_cron``true`Cron requests are profiled by default`profile_cli``false`WP-CLI support exists but is off by default### Filtering

[](#filtering)

The runtime filter model uses nested context filters:

```
[
    'include' => [
        'http' => ['*'],
        'ajax' => ['*'],
        'cron' => ['*'],
        'cli' => ['*'],
    ],
    'exclude' => [
        'http' => [
            '/wp-content/uploads/*',
            '/favicon.ico',
        ],
        'ajax' => [],
        'cron' => [],
        'cli' => [],
    ],
    'exclude_user_agents' => [
        'bot',
        'crawler',
        'spider',
    ],
]
```

`http`, `ajax`, `cron`, and `cli` all support:

- `*` and `.*` wildcard matching
- glob-style patterns through `fnmatch()`
- regex patterns like `/^POST \/wp-admin/`

### Admin UI vs runtime filters

[](#admin-ui-vs-runtime-filters)

The admin page covers the common operational settings:

- API key
- enable profiling
- sample rate
- API URL
- timeout
- proxy
- profile admin
- profile AJAX
- profile cron
- profile WP-CLI
- HTTP status codes to submit
- feature flags
- HTTP include patterns
- HTTP exclude patterns
- excluded user agents

The admin UI writes the same nested `include` / `exclude` structure used by the runtime. It currently exposes the HTTP filter lists directly and preserves any existing AJAX, cron, and CLI filter arrays already present in saved config.

The HTTP status code setting accepts comma-separated values or ranges such as `200-299, 500-599, 404`. The default is `200-299, 500-599`. Leave it empty if you want to drop all HTTP trace submissions.

Feature flags
-------------

[](#feature-flags)

The plugin passes SDK feature flags straight through to the Perfbase extension.

Common flags exposed in the admin UI include:

- `UseCoarseClock`
- `TrackCpuTime`
- `TrackPdo`
- `TrackHttp`
- `TrackCaches`
- `TrackMongodb`
- `TrackElasticsearch`
- `TrackQueues`
- `TrackFileOperations`

Programmatic configuration can also use the broader flag set from `perfbase/php-sdk`.

Example:

```
define(
    'PERFBASE_FLAGS',
    \Perfbase\SDK\FeatureFlags::UseCoarseClock |
    \Perfbase\SDK\FeatureFlags::TrackCpuTime |
    \Perfbase\SDK\FeatureFlags::TrackPdo
);
```

How it works
------------

[](#how-it-works)

The plugin creates one lifecycle object per request context:

- `HttpRequestLifecycle`
- `AjaxRequestLifecycle`
- `CronLifecycle`
- `CliLifecycle`

At a high level:

1. The plugin boots on `plugins_loaded`
2. It loads config and attempts to create the shared SDK client
3. On `init`, it detects the current context and starts the appropriate lifecycle
4. During the request, lightweight hooks add WordPress-specific attributes
5. On shutdown, HTTP requests are only submitted if their status code is in `profile_http_status_codes`
6. On `shutdown`, the lifecycle stops the span and submits the trace

The plugin also adds context through WordPress hooks such as:

- outbound HTTP hooks
- theme and plugin lifecycle hooks
- user, post, comment, REST API, and WooCommerce hooks when available

Cache profiling itself is handled by the native Perfbase extension via feature flags rather than by WordPress cache hooks.

Perfbase can send:

- function call trees, function names, source file paths and line numbers, timing, CPU, memory, and host resource metrics
- host operating system, kernel, hostname, CPU architecture, CPU details, disk capacity details, memory usage, CPU usage, disk I/O, and network I/O samples
- capped process-list snapshots when enabled, containing process ID, executable basename, OS user, CPU usage, memory usage, and process runtime, without command-line arguments
- additional native trace metadata such as normalized SQL query text, database DSN/host/database/username/port metadata, MongoDB or Elasticsearch query/filter payload summaries, Redis or Memcached keys and fields, HTTP URL or URI metadata that may include query strings depending on the PHP API or HTTP library used, HTTP method/status/timing/byte-count metadata, file paths and file operation metadata, mail recipient and subject metadata, shell/process command strings, AWS operation names, OPcache and JIT statistics, PHP error or exception samples, compiled file paths, magic method counts, and truncated function argument values when argument capture is separately configured. These fields depend on enabled extension features, loaded PHP libraries, and which code paths run during the trace
- WordPress request metadata such as action name, HTTP method, request URL without query string, HTTP status code, user IP address, user agent, logged-in user ID when available, hostname, environment, application version, PHP version, WordPress version, and Perfbase plugin version
- WordPress context metadata such as AJAX action, REST route, admin page, post/page identifiers, post type/status, taxonomy context, template and theme information, conditional page type flags, plugin lifecycle context, and WooCommerce page, cart, product, or order context when available
- operational summaries such as memory usage, database query count and timing summaries when available, and sanitized outbound HTTP request metadata when HTTP tracking is enabled

Perfbase does not collect:

- source code
- request bodies, full POST payloads (`$_POST`), arbitrary form fields, or uploaded file contents
- cookie values (`$_COOKIE`) or PHP session data (`$_SESSION`)
- authorization header values
- passwords, API keys, nonces, or session IDs from WordPress request, cookie, or session data
- command-line arguments for process-list snapshots

Feature flags control the extra native trace metadata listed under "Perfbase can send", including outbound HTTP URLs or URIs with query strings for some HTTP libraries and truncated function argument values if argument capture is separately configured. Review enabled Perfbase extension feature flags before profiling sensitive workloads, especially flags that capture arguments, errors, exceptions, database/cache/HTTP/file metadata, mail metadata, process metadata, OPcache metadata, or host resource metadata.

Request metadata
----------------

[](#request-metadata)

The plugin keeps action names low-cardinality and avoids leaking sensitive query parameters.

### Core trace attributes

[](#core-trace-attributes)

- `action` in the format `GET /path`
- `user_id` when logged in
- `user_ip`
- `user_agent`
- `hostname`
- `environment`
- `app_version`
- `php_version`
- `http_method`
- `http_url`
- `http_status_code`

### WordPress-specific attributes

[](#wordpress-specific-attributes)

- `wordpress.version`
- `perfbase.version`
- `wordpress.ajax_action`
- `wordpress.rest_route`
- `wordpress.admin_page`
- template, theme, post, taxonomy, and conditional-tag attributes when available

`http_url` for the inbound WordPress request is stored without the query string. Important WordPress query parameters are broken out into dedicated attributes instead. Native HTTP metadata may still include full outbound URLs or URIs with query strings depending on enabled extension features and the HTTP library used.

### Data Perfbase does not collect

[](#data-perfbase-does-not-collect)

Perfbase does not collect:

- source code
- request bodies, full POST payloads (`$_POST`), arbitrary form fields, or uploaded file contents
- cookie values (`$_COOKIE`) or PHP session data (`$_SESSION`)
- authorization header values
- passwords, API keys, nonces, or session IDs from WordPress request, cookie, or session data
- command-line arguments for process-list snapshots

Database metadata added by the WordPress plugin is limited to aggregate query counts and timing information when available. Native HTTP metadata can include outbound URLs or URIs with query strings. The native profiler may capture additional context depending on enabled Perfbase extension feature flags and application code.

Example production setup
------------------------

[](#example-production-setup)

For a typical production site:

```
define('PERFBASE_ENABLED', true);
define('PERFBASE_API_KEY', getenv('PERFBASE_API_KEY'));
define('PERFBASE_SAMPLE_RATE', 0.02);
define('PERFBASE_TIMEOUT', 5);
define(
    'PERFBASE_FLAGS',
    \Perfbase\SDK\FeatureFlags::UseCoarseClock |
    \Perfbase\SDK\FeatureFlags::TrackCpuTime |
    \Perfbase\SDK\FeatureFlags::TrackPdo
);
```

That gives you low overhead while still capturing a useful stream of production traces.

Troubleshooting
---------------

[](#troubleshooting)

### The plugin says the extension is unavailable

[](#the-plugin-says-the-extension-is-unavailable)

Check that the extension is loaded:

```
php -m | grep perfbase
php --ini
```

If the extension is missing, repeat the manual extension installation steps above or run the automated installer on a supported server:

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

### No traces are appearing

[](#no-traces-are-appearing)

Check these first:

- profiling is enabled
- the API key is present
- the extension is loaded
- the current request type is allowed by your profile toggles
- your sample rate is not set too low
- the request is not blocked by filters or excluded user-agent rules

### High overhead

[](#high-overhead)

To reduce overhead:

- lower `sample_rate`
- use `UseCoarseClock`
- disable feature flags you do not need
- avoid profiling admin traffic unless you need it
- narrow your include filters

Development
-----------

[](#development)

Useful commands:

```
composer test
composer phpstan
composer phpcs:syntax
composer phpcs
composer lint
```

The repository includes unit, integration, and functional tests. `composer phpcs` is the focused WordPress security gate for release checks; use `composer phpcs:syntax` for the lightweight PHP syntax-only check.

Documentation
-------------

[](#documentation)

Full documentation is available at [perfbase.com/docs](https://perfbase.com/docs).

- **Docs**: [perfbase.com/docs](https://perfbase.com/docs)
- **Issues**: [github.com/perfbaseorg/wordpress/issues](https://github.com/perfbaseorg/wordpress/issues)
- **Support**:

Release packaging
-----------------

[](#release-packaging)

Build the installable release ZIP from a clean checkout by passing the tag or release version:

```
bin/build-release-zip v1.2.3
```

The generated ZIP is written to `dist/perfbase-.zip` and includes production Composer dependencies only. Use this same ZIP for GitHub Releases and WordPress.org distribution.

Release checklist:

1. Run `composer test`, `composer phpstan`, `composer phpcs:syntax`, and `composer phpcs`.
2. Tag the release as `v`, for example `v1.2.3`.
3. Push the tag. GitHub Actions builds, verifies, and uploads the installable ZIP to the GitHub Release.
4. Use the same generated package contents for WordPress.org SVN.

To reproduce the tagged package locally:

```
bin/build-release-zip v1.2.3
bin/verify-release-zip dist/perfbase-1.2.3.zip v1.2.3
```

`bin/build-wporg-zip` remains available as a compatibility wrapper around `bin/build-release-zip`.

License
-------

[](#license)

GPL-2.0-or-later. See [LICENSE.txt](LICENSE.txt).

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance96

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

17

Last Release

20d ago

PHP version history (2 changes)v1.0.0PHP >=7.4 <8.5

v1.0.1PHP >=7.4 <8.6

### Community

Maintainers

![](https://www.gravatar.com/avatar/85d93938cbda24f3ae1b325d2c1ac89e95f1f845365395a693bad51e8b61b5d9?d=identicon)[BenPoulson](/maintainers/BenPoulson)

---

Top Contributors

[![benpoulson](https://avatars.githubusercontent.com/u/1797843?v=4)](https://github.com/benpoulson "benpoulson (25 commits)")

---

Tags

apmphpwordpressmonitoringwordpressprofilingapmPerfbase

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/perfbase-wordpress/health.svg)

```
[![Health](https://phpackages.com/badges/perfbase-wordpress/health.svg)](https://phpackages.com/packages/perfbase-wordpress)
```

###  Alternatives

[scoutapp/scout-apm-laravel

Scout Application Performance Monitoring Agent - https://scoutapm.com

23838.1k](/packages/scoutapp-scout-apm-laravel)[scoutapp/scout-apm-php

Scout Application Performance Monitoring Agent - https://scoutapm.com

17885.0k5](/packages/scoutapp-scout-apm-php)[sobanvuex/php-newrelic

PHP Library for New Relic Agent

16520.7k5](/packages/sobanvuex-php-newrelic)[upscale/swoole-newrelic

New Relic APM monitoring of Swoole web-server

1619.7k](/packages/upscale-swoole-newrelic)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)