Perfbase for Joomla

Joomla integration for Perfbase.

This package is a thin adapter over perfbase/php-sdk. It connects Joomla request and console lifecycle events to the Perfbase SDK while leaving extension interaction, payload construction, and submission to the shared SDK.

Support Matrix

Component	Supported
PHP	>=8.1 <9.0
Joomla	4.4 and 5.x
Package type	Joomla system plugin
Runtime contexts	HTTP and CLI
Perfbase SDK	^1.0.0
Perfbase PHP extension	Required at runtime

This package supports:

• Site requests
• Administrator requests when profile_admin is enabled
• Joomla API requests as standard HTTP contexts
• Joomla console commands

This package does not currently provide:

• Dedicated Joomla scheduler or task lifecycles
• Deep component or template execution timelines beyond the main trace span
• End-to-end instrumentation tests inside full Joomla application installs

Features

• HTTP profiling via Joomla lifecycle hooks
• CLI profiling for Joomla console commands
• Low-cardinality action and span naming
• Sanitized HTTP URLs without query strings
• Include and exclude filters for HTTP and CLI
• Production-safe failure handling
• Shutdown fallback cleanup for interrupted execution paths
• Runtime config validation for malformed adapter settings

Installation

1. Download the installable ZIP

Download the perfbase-joomla-<version>.zip artifact from the matching GitHub Release.

Release ZIPs are self-contained Joomla plugin artifacts. They include the production perfbase/php-sdk dependency under the plugin's own vendor/ directory, so normal Joomla Extension Manager installs do not require a Composer install in the Joomla root.

2. Install the ZIP in Joomla

In Joomla administrator, go to:

System -> Install -> Extensions -> Upload Package File

Upload the release ZIP.

Updates

The plugin registers a Joomla update server:

https://raw.githubusercontent.com/perfbaseorg/joomla/main/updates/perfbase.xml

After the first ZIP install, Joomla can discover future releases through the administrator extension update UI. Release metadata points Joomla at the matching GitHub Release ZIP.

3. Enable the plugin

In Joomla administrator, enable:

System - Perfbase

4. Install the Perfbase PHP extension

The plugin depends on the Perfbase PHP extension at runtime. Without the extension, the plugin degrades safely but no traces will be captured.

Development install

For local development, place the source checkout under:

plugins/system/perfbase

Then install dependencies from the plugin directory:

composer install --no-dev --prefer-dist

Quick Start

1. Install and enable the Perfbase PHP extension.
2. Install the release ZIP through Joomla Extension Manager.
3. Enable System - Perfbase in Joomla administrator.
4. Configure api_key.
5. Set enabled = yes.
6. Start with sample_rate = 0.1.
7. Leave profile_admin = no until you want administrator coverage explicitly.

Configuration

The plugin configuration UI is defined in perfbase.xml. Runtime normalization and validation live in ConfigResolver.php.

Core Settings

Setting	Default	Description
enabled	false	Master switch for profiling
api_key	empty	Required Perfbase project API key
api_url	https://ingress.perfbase.cloud	Perfbase receiver URL
sample_rate	0.1	Fraction of requests and commands to profile
timeout	5	SDK request timeout in seconds
proxy	empty	Optional proxy URL
flags	8145	Curated Perfbase feature-flag bitmask

Context Settings

Setting	Default	Description
profile_admin	false	Include administrator requests
profile_http_status_codes	200-299,500-599	HTTP status codes that should be submitted
environment	empty	Optional environment override
app_version	empty	Optional application-version override
include_http	*	Newline-separated HTTP include filters
exclude_http	empty	Newline-separated HTTP exclude filters
include_console	*	Newline-separated CLI include filters
exclude_console	empty	Newline-separated CLI exclude filters

Error Handling

Setting	Default	Description
debug	false	Re-throw profiling errors during development
log_errors	true	Log profiling errors when debug mode is off

Filter Syntax

HTTP and CLI filters support:

• * or .* to match everything
• glob patterns like cache:* or api/*
• regex patterns like /^GET /

Examples:

include_http
*
GET com_content:article:display
api

exclude_http
/administrator/cache/*
/health

include_console
cache:*
database:*

Filters are matched against normalized identifiers rather than raw query-heavy URLs.

profile_http_status_codes accepts comma-separated values, newline-separated values, and ranges such as 200-299,500-599 or 200,201,404. The runtime config is normalized to an integer allowlist. Leave it blank if you want to disable HTTP trace submission entirely.

Runtime Behavior

HTTP

The plugin uses:

• onAfterInitialise
• onAfterRoute
• onAfterDispatch
• onAfterRespond
• register_shutdown_function

HTTP actions are normalized to:

• METHOD option:view:task when Joomla route metadata exists
• METHOD /sanitized/path when it does not

Examples:

• GET com_content:article:display
• POST /users/{id}

By default, 2xx and 5xx HTTP responses are submitted. A 404 will still be profiled in-process, but the trace is discarded unless profile_http_status_codes includes 404.

CLI

CLI spans are derived from the first non-option command token in $_SERVER['argv'].

Example:

• cache:clean -> console_cache_clean

Captured Attributes

HTTP Attributes

• source=http
• action
• http_method
• http_url
• http_status_code
• user_ip
• user_agent
• user_id
• hostname
• php_version
• environment
• app_version
• joomla.client
• joomla.option
• joomla.view
• joomla.task
• joomla.format

Notes:

• http_url excludes the query string
• action is low-cardinality by design
• administrator requests are excluded unless profile_admin is enabled

CLI Attributes

• source=console
• action
• cli.command
• hostname
• php_version
• environment
• app_version

Operational Notes

• If the SDK cannot be initialized, the plugin fails open and does not break the host application.
• If the Perfbase extension is unavailable, the plugin no-ops safely.
• Invalid adapter config is validated at boot and logged in production mode.
• In production, profiling errors are logged only when log_errors is enabled.
• In development, set debug = yes if you want profiling errors to surface immediately.

Verification

Current package verification:

• PHPUnit: passing
• PHPStan: passing on src/
• Overall line coverage: 99.52%
• Overall method coverage: 98.55%

Key class coverage:

• PerfbasePlugin.php: 100% methods, 100% lines
• HttpRequestLifecycle.php: 100% methods, 100% lines
• SpanNaming.php: 100% methods, 100% lines

CI coverage includes:

• the supported PHP baseline
• PHPUnit
• PHPStan
• Joomla framework-package smoke checks for the supported 4.4 and 5.x dependency lines
• both HTTP and CLI smoke paths via tests/Host/joomla-smoke.php
• provider autoload coverage via tests/Host/provider-autoload-smoke.php
• local CMS stubs layered on top of joomla/di and joomla/event

The smoke job is not a full joomla/cms application install. It validates adapter compatibility against the supported Joomla framework-package lines plus local CMS stubs.

Commands used during development:

composer run test
./vendor/bin/phpstan analyse --memory-limit=2G --debug src

Release artifacts are built automatically when a v<semver> tag is pushed on a commit reachable from main. The release workflow checks that the tag version matches perfbase.xml, builds dist/perfbase-joomla-<version>.zip, verifies the ZIP contents, attaches it to the GitHub Release, and commits updated Joomla update metadata to updates/perfbase.xml on main.

To build the same ZIP locally:

bin/build-release-zip v1.0.0
bin/verify-release-zip dist/perfbase-joomla-1.0.0.zip
bin/update-joomla-update-metadata v1.0.0
bin/verify-joomla-update-metadata

In this sandbox, composer run phpstan may fail because PHPStan tries to open a local TCP worker socket. The direct command above was used for the clean static-analysis run.

Development

composer install
composer run test
./vendor/bin/phpstan analyse --memory-limit=2G --debug src

Important files:

• perfbase.xml
• services/provider.php
• updates/perfbase.xml
• ConfigResolver.php
• PerfbasePlugin.php
• tests/
• ci.yml

Documentation

Full documentation is available at perfbase.com/docs.

• Docs: perfbase.com/docs
• Issues: github.com/perfbaseorg/joomla/issues
• Support: support@perfbase.com

License

Apache-2.0. See LICENSE.txt.