---
title: "PHP Library"
slug: "php-library"
description: "Track data server-side with the Mapp Intelligence PHP Library: setup options, instance lifecycle and examples for server-side, hybrid and critical tracking."
status: "update"
updated: 2026-11-02T16:58:47Z
published: 2026-11-02T16:58:47Z
canonical: "docs.mapp.com/php-library"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP Library

The Mapp Intelligence PHP Library provides a server-side integration for sending tracking data directly from your backend to Mapp Intelligence. It enables full or partial server-side tracking, for example to record orders, confirmations, or other events without relying on client-side scripts.

Before using the PHP Library, make sure you have read the [Server-to-Server Basics](/v1/docs/server-to-server) section. That page explains the general tracking structure, request format, parameters, and session handling logic that apply to all server-to-server integrations.

---

## Overview

| **Aspect** | **Description** |
| --- | --- |
| Library name | mapp-digital/mapp-intelligence-tracking |
| Purpose | Server-side data collection for Mapp Intelligence |
| Use cases | Product, order, shipment, and application tracking |
| Integration | Composer (see [Integration & Configuration](/v1/docs/php-integration-and-configuration)) |

---

## Lifecycle

A tracking instance carries the data of the current HTTP request (user agent, IP, cookies, ever ID). Create one instance per request and close it:

```php
$mappIntelligence = new MappIntelligence($mappIntelligenceConfig);
$mappIntelligence->track($data);
$mappIntelligence->close(); // sends the remaining requests, also called when the instance is destroyed
```

`MappIntelligence::getInstance()` keeps working for classic PHP-FPM setups, where every request starts a new process. In long-running PHP runtimes (RoadRunner, Swoole, FrankenPHP worker mode, Laravel Octane) static state survives the request: use one instance per request or call `MappIntelligence::reset()` at the end of every request, otherwise data of one user ends up in the requests of another. See [Classes](/v1/docs/php-classes).

---

## Key Concepts

The PHP library can be used in different tracking setups depending on your data protection requirements and system architecture. Each approach determines how data is collected and forwarded to Mapp Intelligence.

---

### 1. Pure Server-Side Tracking

All tracking requests are created and sent from your server using the PHP library. This approach does not rely on any client-side scripts or cookies and is ideal for environments with strict data protection or limited browser access.

Key Features:

- All consumer types are supported (FILE, FILE_ROTATION, CURL, or custom).
- A unique user identifier (everID) must be passed manually (via setUserId() or a custom ID).
- Tracking data is sent directly to the track server without browser dependencies.
- Depending on browser and caching behavior, this approach may slightly affect page impression counts.

#### Tracking Considerations

Pure server-side tracking or the use of the server-side library to track all page requests might affect the number of page impressions if one of the following conditions is true:

- **Preloading of pages in search results**

Some browsers (for example, Safari or Google Chrome) preload websites in the background when they appear in search results. Since this generates a server call, a page impression may be counted even if the user never opened the page. This can lead to increased page impressions, higher bounce rates, and shorter visit durations.
- **Caching of pages**

If pages are cached in the browser to improve performance, a page impression may not be tracked if the cache prevents a new server call. This can slightly reduce the total number of tracked page impressions and may affect path analyses for previous and following pages.

#### Configuration Example

```php
$mappIntelligenceConfig = new MappIntelligenceConfig();
$mappIntelligenceConfig->setTrackDomain("analytics01.wt-eu02.net")
    ->setTrackId("111111111111111")
    ->setConsumerType(MappIntelligenceConsumerType::FILE_ROTATION)
    ->setForceSSL(true);

$mappIntelligence = MappIntelligence::getInstance($mappIntelligenceConfig);
```

---

### 2. Hybrid Tracking (Pixel + PHP Library)

Combining the PHP library with the Mapp tracking pixel allows you to use both client- and server-side data sources.

This setup provides maximum flexibility, for example tracking user interactions via the pixel while recording page-related data via the server.

Key Features:

- Data is collected by both the tracking pixel and the PHP library.
- No custom track domain is required.
- Pixel requests are forwarded to the server library (`MappIntelligenceHybrid`), which stores them with the FILE or FILE_ROTATION consumer (or your CUSTOM consumer). A [cron job](/v1/docs/php-cron-job) sends the files to the track server. The consumer types CURL and FORK_CURL are replaced by FILE.

#### Configuration Example

```php
$mappIntelligenceConfig = new MappIntelligenceConfig();
$mappIntelligenceConfig->setTrackDomain("analytics01.wt-eu02.net")
    ->setTrackId("111111111111111")
    ->setConsumerType(MappIntelligenceConsumerType::FILE_ROTATION)
    ->setForceSSL(true);

// endpoint for the pixel requests: writes the request to the file and responds with a 1x1px gif
$mappIntelligenceHybrid = new MappIntelligenceHybrid($mappIntelligenceConfig);
$mappIntelligenceHybrid->run();
```

---

### 3. Tracking Mission-Critical Information

Use the PHP library exclusively for mission-critical data (for example, orders, confirmations, or shipping events), while the tracking pixel continues to collect less sensitive data.

Key Features:

- Reduces load on the customer’s server.
- The pixel sends regular browser data directly to the track server.
- The PHP library uses the CURL consumer to send critical data directly to the track server (with `flush()`, `close()` or at the end of the request).

#### Configuration Example

```php
$mappIntelligenceConfig = new MappIntelligenceConfig();
$mappIntelligenceConfig->setTrackDomain("analytics01.wt-eu02.net")
    ->setTrackId("111111111111111")
    ->setConsumerType(MappIntelligenceConsumerType::CURL)
    ->setMaxAttempt(3)
    ->setAttemptTimeout(100)
    ->setMaxBatchSize(1)
    ->setForceSSL(true);

$mappIntelligence = MappIntelligence::getInstance($mappIntelligenceConfig);
```

---

### 4. Server Library as Track Domain

All requests are collected through the tracking pixel but routed via your server to Mapp Intelligence.

This approach hides the Mapp track domain from the browser and allows full client-side functionality while retaining server control.

> [!TIP]
> **Recommendation**
> 
> Use the [MappIntelligenceHybrid](/v1/docs/php-classes) with [Cronjob](/v1/docs/php-cron-job) logic for this use case.