PHPackages                             simplestats-io/php-client - 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. simplestats-io/php-client

ActiveLibrary

simplestats-io/php-client
=========================

Plain PHP client for SimpleStats analytics. Works with any PHP application.

10[1 PRs](https://github.com/simplestats-io/php-client/pulls)PHPCI passing

Since Mar 10Pushed 5d agoCompare

[ Source](https://github.com/simplestats-io/php-client)[ Packagist](https://packagist.org/packages/simplestats-io/php-client)[ RSS](/packages/simplestats-io-php-client/feed)WikiDiscussions main Synced today

READMEChangelog (1)DependenciesVersions (2)Used By (0)

PHP Client for SimpleStats.io
=============================

[](#php-client-for-simplestatsio)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3dfd16faf486ac554c372277e79802a95af6307ddf92bb4d685dcbff67253b42/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73696d706c6573746174732d696f2f7068702d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/simplestats-io/php-client)[![Tests](https://github.com/simplestats-io/php-client/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/simplestats-io/php-client/actions/workflows/run-tests.yml)[![Check & fix styling](https://github.com/simplestats-io/php-client/actions/workflows/fix-php-code-style-issues.yml/badge.svg?branch=main)](https://github.com/simplestats-io/php-client/actions/workflows/fix-php-code-style-issues.yml)[![License](https://camo.githubusercontent.com/3e5c81e24ffc9cba7136cc9ecfe0ac9dd309badcdfbf4ac187b926907da651c8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f73696d706c6573746174732d696f2f7068702d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/simplestats-io/php-client)

This is the official plain PHP client to send tracking data to . It works with any PHP 8.2+ application, no framework required.

For Laravel applications, use the dedicated [Laravel Client](https://github.com/simplestats-io/laravel-client) instead, which provides automatic middleware, observers, and queue integration.

Introduction
------------

[](#introduction)

***SimpleStats*** is a streamlined analytics tool that goes beyond simple page views. It offers **precise insights** into user origins and behaviors through server-side tracking. With default tracking and filtering via [UTM](https://en.wikipedia.org/wiki/UTM_parameters) codes, you gain detailed analysis of **marketing** campaigns, identifying which efforts drive **revenue**. Effortlessly evaluate campaign **ROI**, discover cost-effective user acquisition channels, and pinpoint the most effective performance channels. *SimpleStats* ensures full **GDPR compliance** and is unaffected by ad blockers since all tracking occurs server-side.

[![screenshot](https://camo.githubusercontent.com/6ceccc3ebb9862cafd664150e82380869bc27ae07fd11cb69c61e53e98d18603/68747470733a2f2f73696d706c6573746174732e696f2f696d616765732f73637265656e73686f742e706e67)](https://camo.githubusercontent.com/6ceccc3ebb9862cafd664150e82380869bc27ae07fd11cb69c61e53e98d18603/68747470733a2f2f73696d706c6573746174732e696f2f696d616765732f73637265656e73686f742e706e67)

Installation
------------

[](#installation)

```
composer require simplestats-io/php-client
```

Quick Start
-----------

[](#quick-start)

```
use SimpleStatsIo\PhpClient\SimplestatsClient;
use SimpleStatsIo\PhpClient\TrackingData;
use SimpleStatsIo\PhpClient\VisitorHashGenerator;

$client = new SimplestatsClient([
    'api_token' => 'your-api-token',
]);

// Generate a GDPR-compliant visitor hash
$visitorHash = VisitorHashGenerator::generate(
    ip: $_SERVER['REMOTE_ADDR'],
    userAgent: $_SERVER['HTTP_USER_AGENT'],
    secretKey: 'your-secret-key'
);

// Auto-extract tracking data from the current request
$trackingData = TrackingData::fromGlobals(appUrl: 'https://yourapp.com');

// Track the visitor
$client->trackVisitor($visitorHash, $trackingData);
```

Configuration
-------------

[](#configuration)

Pass a configuration array when creating the client:

```
$client = new SimplestatsClient([
    'api_token'   => 'your-api-token',             // Required
    'api_url'     => 'https://simplestats.io/api/v1/', // Optional (default: SaaS URL)
    'timeout'     => 5,                             // Optional, seconds (default: 5)
    'max_retries' => 3,                             // Optional (default: 3)
    'enabled'     => true,                          // Optional (default: true)
]);
```

OptionTypeDefaultDescription`api_token`string(required)Your project API token from SimpleStats`api_url`string`https://simplestats.io/api/v1/`API base URL (change for self-hosted)`timeout`int`5`HTTP request timeout in seconds`max_retries`int`3`Number of retries on transient failures`enabled`bool`true`Set to `false` to disable all trackingWhen tracking is disabled, all methods return an empty array without making any HTTP requests.

Usage
-----

[](#usage)

### Tracking Visitors

[](#tracking-visitors)

Track anonymous visitors with optional UTM parameters and metadata:

```
$client->trackVisitor(
    visitorHash: $visitorHash,
    trackingData: $trackingData,
    time: new DateTimeImmutable() // optional, defaults to now
);
```

### Tracking User Registrations

[](#tracking-user-registrations)

```
$client->trackUser(
    id: $user->id,
    registeredAt: new DateTimeImmutable($user->created_at),
    trackingData: $trackingData, // optional
    addLogin: true               // optional, also track a login event
);
```

### Tracking Logins

[](#tracking-logins)

```
$client->trackLogin(
    userId: $user->id,
    userRegisteredAt: new DateTimeImmutable($user->created_at),
    ip: $_SERVER['REMOTE_ADDR'],       // optional
    userAgent: $_SERVER['HTTP_USER_AGENT'], // optional
    time: new DateTimeImmutable()       // optional, defaults to now
);
```

### Tracking Payments

[](#tracking-payments)

Amounts must be in **cents** (e.g., 2000 = $20.00). Currency must be [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) (EUR, USD, GBP, etc.).

Associate a payment with either a user or a visitor:

```
// Payment linked to a registered user
$client->trackPayment(
    id: $payment->id,
    gross: 2000,
    net: 1680,
    currency: 'EUR',
    time: new DateTimeImmutable($payment->created_at),
    userId: $user->id,
    userRegisteredAt: new DateTimeImmutable($user->created_at)
);

// Payment linked to an anonymous visitor (e.g., guest checkout)
$client->trackPayment(
    id: $payment->id,
    gross: 2000,
    net: 1680,
    currency: 'EUR',
    time: new DateTimeImmutable($payment->created_at),
    visitorHash: $visitorHash
);
```

### Tracking Custom Events

[](#tracking-custom-events)

```
$client->trackCustomEvent(
    id: 'evt_123',
    name: 'subscription_upgraded',
    time: new DateTimeImmutable(),  // optional, defaults to now
    userId: $user->id,              // optional
    userRegisteredAt: new DateTimeImmutable($user->created_at) // optional
);
```

Tracking Data
-------------

[](#tracking-data)

The `TrackingData` class holds visitor metadata (IP, user agent, UTM parameters, referer, page entry).

### Auto-extract from the current request

[](#auto-extract-from-the-current-request)

```
$trackingData = TrackingData::fromGlobals(appUrl: 'https://yourapp.com');
```

This automatically extracts:

- **IP address** from proxy-aware headers (Cloudflare, Akamai, X-Forwarded-For, X-Real-IP, REMOTE\_ADDR)
- **User agent** from the request
- **UTM parameters** from query string (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `ref`, `referer`, `referrer`, `adGroup`, `adGroupId`)
- **Referer** domain from the HTTP referer header (self-referrals excluded via `appUrl`)
- **Page entry** path (URI without query string)

### Build manually

[](#build-manually)

```
$trackingData = new TrackingData(
    ip: '203.0.113.50',
    userAgent: 'Mozilla/5.0 ...',
    referer: 'google.com',
    source: 'google',
    medium: 'cpc',
    campaign: 'spring_sale',
    term: 'analytics tool',
    content: 'banner_ad',
    pageEntry: '/pricing',
);
```

Visitor Hash Generator
----------------------

[](#visitor-hash-generator)

Generate GDPR-compliant anonymized visitor identifiers. The hash rotates daily to prevent long-term tracking.

```
use SimpleStatsIo\PhpClient\VisitorHashGenerator;

$hash = VisitorHashGenerator::generate(
    ip: $_SERVER['REMOTE_ADDR'],
    userAgent: $_SERVER['HTTP_USER_AGENT'],
    secretKey: 'your-secret-key',
    date: '2024-06-15' // optional, defaults to today
);
```

The generator creates a SHA-256 hash from IP + User-Agent + date + secret key, truncated to 32 characters. The daily date rotation ensures hashes are not persistent across days, keeping visitor tracking fully anonymous.

Error Handling
--------------

[](#error-handling)

The client throws specific exceptions you can catch:

```
use SimpleStatsIo\PhpClient\Exceptions\ConfigurationException;
use SimpleStatsIo\PhpClient\Exceptions\ApiRequestFailed;

try {
    $client->trackVisitor($visitorHash, $trackingData);
} catch (ConfigurationException $e) {
    // Invalid configuration (e.g., missing api_token)
} catch (ApiRequestFailed $e) {
    // API request failed after retries
    $e->getMessage();    // Error description
    $e->statusCode;      // HTTP status code
    $e->responseBody;    // Raw response body
}
```

The HTTP client automatically retries on transient failures (connection errors, 429, 5xx) with exponential backoff.

Performance: Non-Blocking Tracking
----------------------------------

[](#performance-non-blocking-tracking)

By default, all tracking calls are **synchronous** and block the current request. In production, you should avoid adding latency to your user-facing responses. Here are a few strategies:

- **`fastcgi_finish_request()`** (recommended for PHP-FPM): Send the response to the client first, then run tracking calls afterwards. Zero dependencies, works out of the box with PHP-FPM.
- **File/SQLite queue with cron**: Write tracking data to a local file or SQLite database, then process it in the background with a cron job. Most reliable approach, but requires a worker setup.
- **Guzzle async requests**: Use Guzzle's `requestAsync()` combined with `fastcgi_finish_request()` to run multiple tracking calls in parallel after the response is sent.

```
// Example: fastcgi_finish_request()
echo $responseBody;
fastcgi_finish_request(); // Response is delivered to the client

$client->trackVisitor($visitorHash, $trackingData); // Runs in the background
```

Testing
-------

[](#testing)

```
composer test
```

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

[](#documentation)

- [Official SimpleStats.io Documentation](https://simplestats.io/docs)
- [API Documentation](https://simplestats.io/docs/api-documentation.html)

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Zacharias Creutznacher](https://github.com/sairahcaz)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

22

—

LowBetter than 25% of packages

Maintenance65

Regular maintenance activity

Popularity2

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 90.9% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cf347b32c0d1fceabbcbce7626ad662faa34738396fd9f774231d55370823713?d=identicon)[Sairahcaz](/maintainers/Sairahcaz)

---

Top Contributors

[![Sairahcaz](https://avatars.githubusercontent.com/u/7384870?v=4)](https://github.com/Sairahcaz "Sairahcaz (10 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

### Embed Badge

![Health badge](/badges/simplestats-io-php-client/health.svg)

```
[![Health](https://phpackages.com/badges/simplestats-io-php-client/health.svg)](https://phpackages.com/packages/simplestats-io-php-client)
```

PHPackages © 2026

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