Home

These pages describe SDK 1.2. For 1.0.x, see this wiki's history.

The OWA SDK for PHP adds Open Web Analytics tracking to a PHP application and calls OWA's REST API.

Requirements

	Version
OWA Server	1.14 or later
PHP	8.2 or later, with ext-json and ext-iconv

Application passwords need OWA Server 2.x.

ext-curl is used when it is installed. Without it the SDK uses PHP streams, which need allow_url_fopen. There are no other dependencies.

SDK 1.0.x works with older OWA servers. For upgrading from it, see Upgrading from 1.0.x.

Installation

composer require open-web-analytics/owa-php-sdk

Without Composer, download a release and load the SDK's own autoloader:

require_once 'owa-php-sdk/owa-autoloader.php';

Creating clients

$sdk = new OwaSdk\sdk( [
    'instance_url' => 'https://owa.example.com/owa/',   // where OWA Server is installed
] );

$tracker = $sdk->createTracker();
$sites   = $sdk->createSites();

Config passed to new OwaSdk\sdk() applies to every client. Config passed to createTracker() or createSites() applies to that client only and overrides it.

Key	Default
instance_url		URL of the OWA Server install
credentials		api_key and auth_key, see Credentials
timeout / connect_timeout	5 / 2	seconds
transport	curl or streams	an OwaSdk\Http\Transport, to supply your own HTTP client
allow_insecure_app_password	false	send an application password to an http:// instance_url, see Application passwords
debug / debug_log	false / PHP's error log	debug messages and the file they go to

The tracker has more settings; see Tracker.

Credentials

The Tracker needs no credentials. The REST clients, such as Sites, need one of:

• an application password (OWA 2.x), see Application passwords
• a key pair:
  1. API key: the OWA user's API key, shown on their profile page in OWA.
  2. Auth key: the install's secret OWA_AUTH_KEY, from its owa-config.php.

When both are set, the application password is used.

The SDK looks for them in this order:

1. The credentials config array
2. The OWA_APP_PASSWORD, OWA_API_KEY and OWA_AUTH_KEY environment variables
3. PHP constants of the same names
4. A local credentials file

Passing credentials in config

$sdk = new OwaSdk\sdk( [
    'instance_url' => 'https://owa.example.com/owa/',
    'credentials'  => [ 'app_password' => 'YOUR_OWA_APP_PASSWORD' ],
] );

// or the key pair
$sdk = new OwaSdk\sdk( [
    'instance_url' => 'https://owa.example.com/owa/',
    'credentials'  => [
        'api_key'  => 'YOUR_OWA_API_KEY',
        'auth_key' => 'YOUR_SECRET_OWA_AUTH_KEY',
    ],
] );

Environment variables

Set OWA_APP_PASSWORD, or OWA_API_KEY and OWA_AUTH_KEY, for the user that runs the PHP process. The SDK reads them with getenv(). Under PHP-FPM, set them in the pool configuration (env[OWA_API_KEY] = ...).

PHP constants

define( 'OWA_APP_PASSWORD', 'your-app-password' );

// or
define( 'OWA_API_KEY', 'your-api-key' );
define( 'OWA_AUTH_KEY', 'your-secret-auth-key' );

Credentials file

An INI file at ~/.owa/credentials, in the home directory of the user that runs the PHP process:

[defaults]
api_key = YOUR_OWA_API_KEY
auth_key = YOUR_SECRET_OWA_AUTH_KEY

or, for an application password:

[defaults]
app_password = YOUR_OWA_APP_PASSWORD

The section may also be named [default], or left out.

Application passwords (OWA 2.x)

An application password is a named, revocable credential for one OWA user. Create one in OWA under My Preferences > Application Passwords, or with the app-password-create CLI command. It is 44 characters and shown once.

Scope	Allows
Read only	GET requests, such as listSites()
Read and write	every request, such as addSite()

The SDK sends it as Authorization: Bearer <password>, with no X-API-KEY and no signature.

It is never sent to an http:// instance_url. The request fails without being sent, and getLastErrors() returns [ 'Application password not sent: instance_url is not https' ]. OWA Server refuses one over plain HTTP too, unless its app_passwords_require_https setting is off. For such an install:

$sites = $sdk->createSites( [ 'allow_insecure_app_password' => true ] );

Behind a proxy that terminates TLS, the proxy must send X-Forwarded-Proto: https or X-Forwarded-Port: 443 for OWA Server to count the request as HTTPS. Apache withholds the Authorization header from PHP-FPM unless it sets CGIPassAuth On, or OWA's own .htaccess copies the header, which needs AllowOverride FileInfo. Without either, every application password is answered 401.

How key-pair requests are signed

With the key pair, every REST request carries the API key in X-API-KEY and a signature in X-SIGNATURE. The signature covers the full request URL, so instance_url must use the scheme, host and port that OWA Server itself sees. Behind a proxy that rewrites the host or terminates TLS, use the URL OWA is configured with (OWA_PUBLIC_URL).

Errors

The SDK does not throw on a failed request. Tracking methods return false, and REST methods return null. getLastErrors() lists the reasons, and getLastResponse() holds the HTTP response:

if ( $sites->listSites() === null ) {
    print_r( $sites->getLastErrors() );   // e.g. [ 'HTTP 401' ] or the API's validation messages
}

A failure is also written to PHP's error log, by method and path only, without credentials or visitor data.

Upgrading from 1.0.x

	1.0.x	1.1
PHP	7.2.5+	8.2+
OWA Server	any 1.x	1.14+
HTTP client	Guzzle	built in; getHttpClient() returns an OwaSdk\Http\Transport
Tracking methods return	a Guzzle response, or null	bool
A failed REST request	Guzzle exception details in the error log, credentials included	null, with reasons in getLastErrors()
Session cookie	owa_s	owa_s_<siteId>, migrated on the visitor's next request
Billing address on addTransaction()	sent under names OWA 1.14 discards	stored
Do Not Track	ignored	respected; see Do Not Track
debug	also turned on display_errors	only writes debug messages

addOrganicSearchEngine() now does nothing; OWA Server classifies referrers itself.

1.2 adds application passwords. getCredentials() now returns app_password beside api_key and auth_key.

Clients

• Tracker
• Sites