README

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

Install and enable the Perfbase PHP extension.
Install the release ZIP through Joomla Extension Manager.
Enable System - Perfbase in Joomla administrator.
Configure api_key.
Set enabled = yes.
Start with sample_rate = 0.1.
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:

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.

perfbase / joomla

Maintainers

Package info

Statistics

Security