---
title: "Classes"
slug: "php-classes"
description: "Reference of the PHP Library classes MappIntelligence, MappIntelligenceHybrid, DataMap, ProductCollection and ParameterMap, incl. lifecycle methods."
status: "update"
updated: 2026-11-02T16:56:16Z
published: 2026-11-02T16:56:16Z
canonical: "docs.mapp.com/php-classes"
---

> ## 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.

# Classes

This section includes the available classes with examples.

**MappIntelligence**

### Methods

#### constructor

Creates a tracking instance. The instance carries the data of the current HTTP request (user agent, IP, cookies, ever ID), so create one instance per request and close it. This is required in long-running PHP runtimes (RoadRunner, Swoole, FrankenPHP worker mode, Laravel Octane), where static state survives the request. For a complete configuration of the Mapp Intelligence PHP library please check [Configuration](/v1/docs/php-integration-and-configuration).

```php
/**
 * @param MappIntelligenceConfig|array|string $config Config object, config array or path to a config file
 */
$mappIntelligence = new MappIntelligence($config);
```

#### getInstance

Returns the shared Mapp Intelligence instance of the current PHP process. The configuration is only used for the first call. In long-running PHP runtimes call `reset()` at the end of every request or use one `new MappIntelligence($config)` per request.

```php
/**
 * @param MappIntelligenceConfig $config
 * @return MappIntelligence
 */
$mappIntelligence = MappIntelligence::getInstance($config);
```

#### reset

Closes the shared instance of `getInstance()` (the remaining requests are sent). The next `getInstance()` call creates a new instance with the data of the current request.

```php
MappIntelligence::reset();
```

#### track

Sends the data to the Mapp track server. For a complete data configuration of the Mapp Intelligence PHP library, please check [Data](/v1/docs/php-data).

Without data, a page request with the default page name is tracked. The request is queued and sent with `flush()`, `close()` or at the end of the request (with `requestInterval` also while requests are added). After `close()` the request is rejected.

```php
/**
 * @param MappIntelligenceParameterMap|MappIntelligenceDataMap|array $data
 * @return bool false if the request was not added (tracking deactivated, instance closed)
 */
$mappIntelligence->track($data);
```

#### flush

Here you can explicitly send the data to the Mapp tracking servers. In most configurations this is done automatically by the PHP runtime environment. Just to be sure, you should call this manually at the end of your script.

```php
/**
 * @return boolean true if every request was delivered, false if requests are still queued or were discarded
 */
$mappIntelligence->flush();
```

#### close

Sends the remaining requests and releases the consumer (HTTP connection, file handle). Afterwards `track()` is rejected. `close()` is called automatically when the instance is destroyed; calling it again has no effect.

```php
/**
 * @return boolean true if no request remains unsent
 */
$mappIntelligence->close();
```

#### setOnFlushComplete

The callback is called after every flush with `true` if all requests were delivered.

```php
/**
 * @param callable|null $callback function (bool $success)
 * @return MappIntelligence
 */
$mappIntelligence->setOnFlushComplete(function ($success) {
    // ...
});
```

#### getTransmittedCampaignsCookie

Returns the cookie with the campaigns already transmitted in this session (campaigns with "once per session", see [Campaign](/v1/docs/campaign-data-object-php-library-s2s)), or `null` if nothing changed. Add it to the HTTP response, otherwise "once per session" cannot work across requests. It is a session cookie and deliberately not HttpOnly, because the client-side pixel reads the same cookie.

```php
/**
 * @return MappIntelligenceCookie|null
 */
$cookie = $mappIntelligence->getTransmittedCampaignsCookie();
if ($cookie) {
    setcookie($cookie->getName(), $cookie->getValue(), 0, $cookie->getPath(), $cookie->getDomain(),
        $cookie->isSecure(), $cookie->isHttpOnly());
}
```

#### getUserIdCookie

It is important to uniquely identify a user to fully benefit from Mapp Intelligence tracking capabilities. Mapp Intelligence uses the everID (eid) internally to keep the tracking information aligned to a user. You can either pass your own unique identifier or you can use the library to use an existing everID (see [Configuration](/v1/docs/php-integration-and-configuration) → setCookie). If you track with both the server-side library and the pixel and you use the getUserIdCookie() method, an eid cookie is returned (see [MappIntelligenceCookie](/v1/docs/php-interfaces)), which you then returned to the client. The method only returns the cookie, it does not send it: add it to the HTTP response yourself. `getMaxAge()` is the maximum age in seconds (180 days); for `setcookie()` use `time() + $cookie->getMaxAge()` as expiry (see [MappIntelligenceCookie](/v1/docs/php-interfaces)).

`null` is returned if

- an everID already exists (from the cookies of the request or from an earlier call),
- the context is `SERVER_SIDE_COOKIE` and the track domain is a Mapp track domain (`*.wt-*.net`, `*.webtrekk.net`, `*.webtrekk-*.net`): a server-side cookie requires your own track domain,
- the context is `CLIENT_SIDE_COOKIE` and the pixel version is not `V4`, `V5` or `SMART`,
- the track ID or the track domain is not configured (logged as ERROR).

In the second and third case, a new everID is still created and used for the requests of this instance. Pass the context as the constants (strings `'1'` and `'3'`); it is compared strictly.

##### Options

| MappIntelligence::V4 | pixelVersion |
| --- | --- |
| MappIntelligence::V5 | pixelVersion |
| MappIntelligence::SMART | pixelVersion |
| MappIntelligence::CLIENT_SIDE_COOKIE | context |
| MappIntelligence::SERVER_SIDE_COOKIE | context |

```php
/**
 * @param string $pixelVersion Version ot the current pixel (v4, v5, smart)
 * @param string $context Cookie context (1, 3)
 *
 * @return MappIntelligenceCookie
 */
$mappIntelligence->getUserIdCookie($pixelVersion, $context);
```

#### setUserId

It is important to uniquely identify a user to fully benefit from Mapp Intelligence tracking capabilities. Mapp Intelligence uses the everID (eid) internally to keep the tracking information aligned to a user. You can either pass your own unique identifier or you can use the library to create it using the setUserId() method. If you track with both the server-side library and the pixel and you use the setUserId() method it will not override the everID (eid) of the pixel. This is only generated if no eid exists yet. Unlike `getUserIdCookie()`, `setUserId()` sends the cookie itself (`setcookie()`). If no cookie is created, nothing is sent.

##### Options

| MappIntelligence::V4 | pixelVersion |
| --- | --- |
| MappIntelligence::V5 | pixelVersion |
| MappIntelligence::SMART | pixelVersion |
| MappIntelligence::CLIENT_SIDE_COOKIE | context |
| MappIntelligence::SERVER_SIDE_COOKIE | context |

```php
/**
 * @param string $pixelVersion Version of the current pixel (v4, v5, smart)
 * @param string $context Cookie context (1, 3)
 *
 * @return bool false if the track ID or the track domain is missing
 */
$mappIntelligence->setUserId($pixelVersion, $context);
```

**MappIntelligenceHybrid**

### Methods

#### constructor

For a complete configuration of the Mapp Intelligence Hybrid please check [Configuration](/v1/docs/php-integration-and-configuration).

The hybrid only writes the pixel requests to files, the [cron job](/v1/docs/php-cron-job) sends them. The consumer types `FILE_ROTATION` and `CUSTOM` are used as configured; every other consumer type (`CURL`, `FORK_CURL` and the default) is replaced by `FILE`.

```php
/**
 * @param MappIntelligenceConfig|array $config Mapp Intelligence configuration
 */
$mappIntelligenceHybrid = new MappIntelligenceHybrid($config);
```

#### setRequestURL

If the query parameters from the current request are not in `$_SERVER['QUERY_STRING']`, please set them before calling `run` (or pass the URL to `track`).

```php
/**
 * @param string $rURL HTTP request url with query parameters
 * @return bool false if the URL is invalid (the current request URL is kept)
 */
$mappIntelligenceHybrid->setRequestURL($rURL);
```

#### run

Reads all query parameters from the current request and saves them in the file. As default response, the method returns a 1x1px transparent gif. Only pixel requests with the parameter `p` and at most 64 KB are written into the log file (see `track`).

```php
/**
 * @param bool $withoutResponse
 */
$mappIntelligenceHybrid->run($withoutResponse);
```

#### track

Reads all query parameters of the pixel request and saves them in the file (without sending a response). Only pixel requests with the parameter `p` and at most 64 KB are accepted (otherwise WARN); the endpoint is public and must not fill the disk. The parameters that only the server adds (`X-WT-IP`, `X-WT-UA`, `X-WT-SEC-CH-UA*`) are removed from the request of the client, so a client cannot pretend to be another user; the library adds them from the configuration. An invalid URL returns `false` and tracks nothing (the previous request is not tracked again).

```php
/**
 * @param string|null $rURL Pixel request URL with query parameters, default is the current request
 * @return bool false if the URL is invalid, there is nothing to track, the tracking is deactivated or the request is no valid pixel request
 */
$mappIntelligenceHybrid->track($rURL);
```

#### flush, close, setOnFlushComplete, getUserIdCookie

Work like the methods of `MappIntelligence`. `getTransmittedCampaignsCookie()` always returns `null`, campaigns are resolved by the client-side pixel in the hybrid mode.

#### getResponseAsBytes

Returns the 1x1px transparent gif as binary string (same as `getResponseAsImage`).

```php
$bytes = $mappIntelligenceHybrid->getResponseAsBytes();
```

#### getResponseAsImage

As response, the method returns a 1x1px transparent gif, which you then returned to the client.

```php
/**
 * @return Returns a 1x1px transparent gif as image.
 */
$image = $mappIntelligenceHybrid->getResponseAsImage();
```

#### getResponseAsBase64

As response, the method returns a 1x1px transparent gif, which you then returned to the client.

```php
/**
 * @return Returns a 1x1px transparent gif as base64.
 */
$imageBase64 = $mappIntelligenceHybrid->getResponseAsBase64();
```

#### Example

```php
require_once __DIR__ . '/vendor/autoload.php';

use MappIntelligence\MappIntelligenceHybrid;
use MappIntelligence\Config\MappIntelligenceConfig;

try {
    $mappIntelligenceConfig = new MappIntelligenceConfig('./config.ini');
    $mappHybrid = new MappIntelligenceHybrid($mappIntelligenceConfig);
    $mappHybrid->run();
} catch (Exception $e) {
    error_log($e->getMessage());
}
```

**MappIntelligenceDataMap**

### Methods

#### constructor

```php
/**
 *
 */
$mappIntelligenceDataMap = new MappIntelligenceDataMap();
```

#### action

```php
/**
 * @param MappIntelligenceAction $data Mapp Intelligence action data
 * @return $this
 */
$mappIntelligenceDataMap->action($data);
```

#### campaign

```php
/**
 * @param MappIntelligenceCampaign $data Mapp Intelligence campaign data
 * @return $this
 */
$mappIntelligenceDataMap->campaign($data);
```

#### customer

```php
/**
 * @param MappIntelligenceCustomer $data Mapp Intelligence customer data
 * @return $this
 */
$mappIntelligenceDataMap->customer($data);
```

#### order

```php
/**
 * @param MappIntelligenceOrder $data Mapp Intelligence order data
 * @return $this
 */
$mappIntelligenceDataMap->order($data);
```

#### page

```php
/**
 * @param MappIntelligencePage $data Mapp Intelligence page data
 * @return $this
 */
$mappIntelligenceDataMap->page($data);
```

#### product

```php
/**
 * @param MappIntelligenceProductCollection $data Mapp Intelligence product collection
 * @return $this
 */
$mappIntelligenceDataMap->product($data);
```

#### session

```php
/**
 * @param MappIntelligenceSession $data Mapp Intelligence session data
 * @return $this
 */
$mappIntelligenceDataMap->session($data);
```

#### registration

```php
/**
 * @param MappIntelligenceRegistration $data Mapp Engage registration data (User Matching)
 * @return $this
 */
$mappIntelligenceDataMap->registration($data);
```

#### engage

```php
/**
 * @param MappIntelligenceEngage $data Mapp Engage data (custom attributes, custom web event)
 * @return $this
 */
$mappIntelligenceDataMap->engage($data);
```

For both, see [Mapp Engage](/v1/docs/mapp-engage-data-object-php-library-s2s).

#### Example

```php
$mappIntelligence = MappIntelligence::getInstance();
$page = new MappIntelligencePage('en.page.test');
$page->setCategory(1, 'page.test')
	->setCategory(2, 'en')
	->setCategory(3, 'page')
	->setCategory(4, 'test');

$session = new MappIntelligenceSession();
$session->setParameter(1, '1');

$customer = new MappIntelligenceCustomer('24');
$customer->setFirstName('John')
	->setLastName('Doe')
	->setEmail('john@doe.com');

$product1 = new MappIntelligenceProduct('065ee2b001');
$product1->setCost(59.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product2 = new MappIntelligenceProduct('085eo2f009');
$product2->setCost(49.99)
	->setQuantity(5)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product3 = new MappIntelligenceProduct('995ee1k906');
$product3->setCost(15.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product4 = new MappIntelligenceProduct('abc');
$product4->setCost(0)
	->setQuantity(0)
	->setSoldOut(true)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$products = new MappIntelligenceProductCollection();
$products->add($product1)
	->add($product2)
	->add($product3)
	->add($product4);

$mappIntelligence->track((new MappIntelligenceDataMap)
	->page($page)
	->order(new MappIntelligenceOrder(360.93))
	->session($session)
	->customer($customer)
	->product($products)
);
```

**MappIntelligenceProductCollection**

### Methods

#### constructor

```php
/**
 *
 */
$mappIntelligenceProductCollection = new MappIntelligenceProductCollection();
```

#### add

```php
/**
 * @param MappIntelligenceProduct $product Mapp Intelligence product data
 * @return $this
 */
$mappIntelligenceProductCollection->add($product);
```

#### Example

```php
$mappIntelligence = MappIntelligence::getInstance();
$product1 = new MappIntelligenceProduct('065ee2b001');
$product1->setCost(59.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product2 = new MappIntelligenceProduct('085eo2f009');
$product2->setCost(49.99)
	->setQuantity(5)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product3 = new MappIntelligenceProduct('995ee1k906');
$product3->setCost(15.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product4 = new MappIntelligenceProduct('abc');
$product4->setCost(0)
	->setQuantity(0)
	->setSoldOut(true)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$products = new MappIntelligenceProductCollection();
$products->add($product1)
	->add($product2)
	->add($product3)
	->add($product4);

$mappIntelligence->track((new MappIntelligenceDataMap)
	->product($products)
);
```

**MappIntelligenceParameterMap**

### Methods

#### constructor

```php
/**
 *
 */
$mappIntelligenceParameterMap = new MappIntelligenceParameterMap();
```

#### add

```php
/**
 * @param string $key Add key to map
 * @param string $value Add value to map
 * @return $this
 */
$mappIntelligenceParameterMap->add($key, $value);
```

#### Example

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

$mappIntelligenceParameterMap = new MappIntelligenceParameterMap();
$mappIntelligenceParameterMap
	->add(MappIntelligenceParameter::$PAGE_NAME, 'en.page.test')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(1), 'page.test')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(2), 'en')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(3), 'page')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(4), 'test')
	->add(MappIntelligenceParameter::$ORDER_VALUE, 360.93)
	->add(MappIntelligenceParameter::$CUSTOMER_ID, '24')
	->add(MappIntelligenceParameter::$FIRST_NAME, 'John')
	->add(MappIntelligenceParameter::$LAST_NAME, 'Doe')
	->add(MappIntelligenceParameter::$EMAIL, 'john@doe.com')
	->add(MappIntelligenceParameter::$PRODUCT_ID, '065ee2b001;085eo2f009;995ee1k906')
	->add(MappIntelligenceParameter::$PRODUCT_COST, '59.99;49.99;15.99')
	->add(MappIntelligenceParameter::$PRODUCT_QUANTITY, '1;5;1')
	->add(MappIntelligenceParameter::$PRODUCT_STATUS, 'conf');

$mappIntelligence->track($mappIntelligenceParameterMap);
```