Download the PHP package simplestats-io/php-client without Composer

PHP Client for SimpleStats.io

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

For Laravel applications, use the dedicated Laravel Client instead, which provides automatic middleware, observers, and queue integration.

Introduction

SimpleStats is analytics that goes beyond simple page views. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. With server-side tracking and filtering via UTM codes, you get detailed analysis of marketing efforts and clearly see which channels drive revenue. Effortlessly evaluate ROI, identify cost-effective user acquisition channels, and pinpoint the most effective performance channels. SimpleStats is fully GDPR compliant and unaffected by ad blockers since all tracking occurs server-side.

Installation

Quick Start

Configuration

Pass a configuration array when creating the client:

When tracking is disabled, all methods return an empty array without making any HTTP requests.

Usage

Tracking Visitors

Track anonymous visitors with optional UTM parameters and metadata:

Tracking User Registrations

Tracking Logins

Tracking Payments

Amounts must be in cents (e.g., 2000 = $20.00). Currency must be ISO 4217 (EUR, USD, GBP, etc.).

Associate a payment with either a user or a visitor:

Tracking Custom Events

Tracking Data

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

Auto-extract from the current request

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

Visitor Hash Generator

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

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

The client throws specific exceptions you can catch:

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

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.

Testing

Documentation

• Official SimpleStats.io Documentation
• API Documentation

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Zacharias Creutznacher
• All Contributors

License

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