---
title: "Integration and Configuration"
slug: "php-integration-and-configuration"
description: "nstall the Mapp Intelligence PHP Library via Composer and configure it with a config object or ini file: all options, defaults and setter rules."
status: "update"
updated: 2026-11-02T16:57:39Z
published: 2026-11-02T16:57:39Z
canonical: "docs.mapp.com/php-integration-and-configuration"
---

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

# Integration and Configuration

## Integration

### Download

Download the Mapp Intelligence tracking library from our github repository [mapp-digital/mapp-intelligence-tracking](https://github.com/mapp-digital/Mapp-Intelligence-PHP-Tracking) and add the tracking library in your PHP code:

```php
use MappIntelligence\MappIntelligence;
```

### Composer

```bash
$ composer require mapp-digital/mapp-intelligence-tracking
```

## Configuration

**Config Object**

```php
$mappIntelligenceConfig = new MappIntelligenceConfig();
$mappIntelligenceConfig->setTrackId("111111111111111")
	->setTrackDomain("analytics01.wt-eu02.net")
	->setDomain(array())
	->addDomain("")
	->setUseParamsForDefaultPageName(array())
	->addUseParamsForDefaultPageName("")
    ->setActivateAdvancedPermission(false)
    ->setAdvancedPermissionCategory(0)

	->setContainsInclude(array())
	->addContainsInclude("")
	->setContainsExclude(array())
	->addContainsExclude("")
	->setMatchesInclude(array())
	->addMatchesInclude("")
	->setMatchesExclude(array())
	->addMatchesExclude("")

	->setLogger(null)
	->setLogLevel(MappIntelligenceLogLevel::ERROR)
	->setDebug(false)
	->setDeactivate(false)

	->setConsumerType("")
	->setConsumer(null)
	->setFilename("/tmp/MappIntelligenceRequests.log")
	->setFileMode("a")
	->setFilePath("/tmp/")
	->setFilePrefix("MappIntelligenceRequests")
	->setMaxAttempt(1)
	->setAttemptTimeout(100)
	->setMaxBatchSize(50)
	->setMaxQueueSize(1000)
	->setConnectionTimeout(30 * 1000)
	->setReadTimeout(5 * 1000)
	->setRequestInterval(0)
	->setMaxFileLines(10000)
    ->setMaxFileDuration(30 * 60 * 1000)
    ->setMaxFileSize(24 * 1024 * 1024)
	->setForceSSL(true)

	->setUserAgent("")
	->setClientHintUserAgent("")
	->setClientHintUserAgentFullVersionList("")
	->setClientHintUserAgentMobile("")
	->setClientHintUserAgentModel("")
	->setClientHintUserAgentPlatform("")
	->setClientHintUserAgentPlatformVersion("")
	->setRemoteAddress("")
	->setReferrerURL("")
	->setRequestURL("")
	->setCookie(array())
	->addCookie("", "");
```

**Methods**

| Methods | Type | Notes | Default | Mandatory |
| --- | --- | --- | --- | --- |
| setTrackId | String | Enter your Mapp Intelligence track ID (provided by Mapp). | empty | yes |
| setTrackDomain | String | Enter your Mapp Intelligence tracking URL. | empty | yes |
| setDomain | String[] | Specify the domains you do not want to identify as an external referrer (e.g. your subdomains). | host of the request URL (with port, except 80 and 443), derived on every `build()` | no |
| addDomain | String | Specify the domain you do not want to identify as an external referrer (e.g. your subdomains). | empty | no |
| setUseParamsForDefaultPageName | String[] | Includes specific URL parameter(s) in the default page name. | empty | no |
| addUseParamsForDefaultPageName | String | Includes specific URL parameter(s) in the default page name. | empty | no |
| setActivateAdvancedPermission | Boolean | Enable if you need to differentiate between additional usage options for the tracked data, e.g., only to your Intelligence instance or to both Intelligence and Engage. | false | no |
| setAdvancedPermissionCategory | Integer | - 0 (default): only Intelligence - 3: Intelligence and Engage | 0 | no |
| setContainsInclude | String[] | Specify the strings that must be contained in the request URL to measure the request. | empty | no |
| addContainsInclude | String | Specify the string that must be contained in the request URL to measure the request. | empty | no |
| setContainsExclude | String[] | Specify the strings that must be contained in the request URL to not measure the request. | empty | no |
| addContainsExclude | String | Specify the string that must be contained in the request URL to not measure the request. | empty | no |
| setMatchesInclude | String[] | Specify the regular expressions that must be match the request URL to measure the request. | empty | no |
| addMatchesInclude | String | Specify the regular expression that must be match the request URL to measure the request. | empty | no |
| setMatchesExclude | String[] | Specify the regular expressions that must be match the request URL to not measure the request. | empty | no |
| addMatchesExclude | String | Specify the regular expression that must be match the request URL to not measure the request. | empty | no |
| setLogger | MappIntelligenceLogger | Activates the debug mode. The debug mode sends messages your own LoggerClass (see [MappIntelligenceLogger](/v1/docs/php-interfaces)). | null | no |
| setLogLevel | Integer or String | Specify the debug log level: - *NONE:* no logs - *FATAL:* fatal errors - *ERROR*: errors leading to data loss or break code - *WARN:* errors that can affect data quality - *INFO:* general info on configuration and send status - *DEBUG*: general info on request sendout and queue status Use the constants of `MappIntelligenceLogLevel` or their names as string (case-insensitive). Other values are ignored. | ERROR | no |
| setDebug | Boolean | Activates the debug mode. The debug mode sends messages to the PHP system logger (Operating System's system logging mechanism or a file, depending on what the **error_log** configuration directive is set to). | false | no |
| setDeactivate | Boolean | Deactivate the tracking functionality. | false | no |
| setConsumerType | String | Specify the [consumer](/v1/docs/php-data-transfer-consumer) to use for data transfer to Intelligence ( *CURL, FORK_CURL*, *FILE, FILE_ROTATION* or *CUSTOM*). | CURL | no |
| setConsumer | MappIntelligenceConsumer | Specify the custom consumer for data transfer to Intelligence (see [MappIntelligenceConsumer](/v1/docs/php-interfaces)). | null | no |
| setFilename | String | Enter the path to your request logging file. This is only relevant when using FILE consumer. | sys_get_temp_dir() . '/MappIntelligence Requests.log' | no |
| setFileMode | String | File mode of the FILE consumer: `a` (append) or `c`. `c` is treated like `a`, the requests are always appended. Other values are ignored silently. | a | no |
| setFilePath | String | Enter the path to your request logging file. This is only relevant when using FILE_ROTATION consumer. | sys_get_temp_dir() . '/' | no |
| setFilePrefix | String | Enter the prefix from your request logging files. This is only relevant when using FILE_ROTATION consumer. | MappIntelligenceRequests | no |
| setMaxAttempt | Integer | Specify the number of send attempts per flush (1 to 5, other values are ignored silently). If the last attempt fails, the requests stay in the queue and are sent again with the next `flush()` or `close()`; requests that are still queued when the instance is closed or destroyed are lost (e.g. CURL with a track server that cannot be reached). In the cron job they stay in the log file for the next run. | `1` | no |
| setAttemptTimeout | Integer | Specify the interval of request resend in milliseconds (1 to 500, other values are ignored silently). | 100 | no |
| setMaxBatchSize | Integer | Specify the maximum request number per batch. Values below 1 count as 1. A full batch is not sent right away: the requests are sent with `flush()`, `close()` or at the end of the request. There is no upper bound, but a batch with more than 10,000 requests is DISCARDED by the built-in consumers. Independent of this value, the queue ends a batch at about 20 MB request body. For the file consumers the value is always 1. | 50 | no |
| setMaxQueueSize | Integer | Specify the maximum number of requests saved in the queue. A full queue is sent first; if it is still full, the oldest requests are discarded with a warning. 0 means unlimited. | 1000 | no |
| setConnectionTimeout | Integer | Connection timeout of the HTTP consumer in milliseconds (0 = no timeout). Not used by FORK_CURL. | 30 * 1000 | no |
| setReadTimeout | Integer | Read timeout of the HTTP consumer in milliseconds (0 = no timeout). cURL has no pure read timeout, so the total time of a batch is limited to connection + read timeout; only if both values are greater than 0, otherwise the total time is not limited. | 5 * 1000 | no |
| setRequestInterval | Integer | Interval in seconds after which the queued requests are sent while new requests are added (0 = off, the requests are sent with `flush()`, `close()` or at the end of the request). | 0 | no |
| setRequestQueues | Integer | Number of request queues. Exists for compatibility with the Java library, PHP processes the requests of one instance in a single queue. | 2 | no |
| setMaxFileLines | Integer | The maximum number of lines per file. A larger value is reduced to the maximum (10 * 1000) with a warning. | 10 * 1000 | no |
| setMaxFileDuration | Integer | The maximum file duration in milliseconds. A larger value is reduced to the maximum (30 * 60 * 1000) with a warning. | 30 * 60 * 1000 | no |
| setMaxFileSize | Integer | The maximum file size in bytes. A larger value is reduced to the maximum (24 * 1024 * 1024) with a warning. | 24 * 1024 * 1024 | no |
| setForceSSL | Boolean | Sends every request via SSL. | true | no |
| setUserAgent | String | Enter the origin client HTTP user agent string. | $_SERVER['HTTP_USER_AGENT'] | no |
| setClientHintUserAgent | String | Enter the origin Client Hint header for "sec-ch-ua" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentFullVersionList | String | Enter the origin Client Hint header for "sec-ch-ua-full-version-list" (see [How can I make my website ready for Google Chrome's Client Hints?](/docs/how-can-i-make-my-website-ready-for-google-chrome-s-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentMobile | String | Enter the origin Client Hint header for "sec-ch-ua-mobile" (see [How can I make my website ready for Google Chrome's Client Hints?](/docs/how-can-i-make-my-website-ready-for-google-chrome-s-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentModel | String | Enter the origin Client Hint header for "sec-ch-ua-model" (see [How can I make my website ready for Google Chrome's Client Hints?](/docs/how-can-i-make-my-website-ready-for-google-chrome-s-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentPlatform | String | Enter the origin Client Hint header for "sec-ch-ua-platform" (see [How can I make my website ready for Google Chrome's Client Hints?](/docs/how-can-i-make-my-website-ready-for-google-chrome-s-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentPlatformVersion | String | Enter the origin Client Hint header for "sec-ch-ua-platform-version" (see [How can I make my website ready for Google Chrome's Client Hints?](/docs/how-can-i-make-my-website-ready-for-google-chrome-s-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setRemoteAddress | String | Enter the origin client Remote address (ip). | $_SERVER['REMOTE_ADDR'] | no |
| setReferrerURL | String | Enter the origin client HTTP referrer URL. | $_SERVER['HTTP_REFERER'] | no |
| setRequestURL | String | Enter the origin client HTTP request URL. The protocol is taken from `$_SERVER['HTTPS']` or `$_SERVER['REQUEST_SCHEME']` (proxy headers like X-Forwarded-Proto are not evaluated, set the URL yourself behind a proxy). | $protocol . "://" . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] | no |
| setCookie | String[] | Enter a array of all origin client cookies. | $_COOKIE | no |
| addCookie | String | Enter a origin client cookie (key, value). | empty | no |

Setters: `null` keeps the current value, every other value (also `false`, `0`, `""` and an empty list) is applied. A list setter (e.g. `setDomain(array())`) replaces the list, an `add…()` method appends to it. Exceptions: setters with a range (`setMaxAttempt()`, `setAttemptTimeout()`, `setLogLevel()`, `setFileMode()`, `setConnectionTimeout()`, `setReadTimeout()` and `setRequestInterval()` below 0, `setMaxFile…()` below 1) ignore a value outside of it, `setRequestURL()` ignores an invalid URL, `setDebug(false)` does not remove a logger that was set before.

> [!NOTE]
> Note
> 
> One configuration and one tracking instance per request: the configuration reads the request data (user agent, IP, cookies, request URL) from `$_SERVER` and `$_COOKIE` when it is built. In long-running PHP runtimes, create them for every request.

**Config Array**

The constructor also accepts an array. Each key is the name of a setter without `set`, for example `trackId` for `setTrackId()` or `maxBatchSize` for `setMaxBatchSize()`. Keys without a matching setter are ignored. The key `config` loads a configuration file first; the other keys of the array are applied afterwards and overwrite its values.

```php
$mappIntelligenceConfig = new MappIntelligenceConfig(array(
	"config" => "path/to/your/config/file/config.ini",
	"trackId" => "111111111111111",
	"trackDomain" => "analytics01.wt-eu02.net",
	"consumerType" => MappIntelligenceConsumerType::FILE_ROTATION,
	"filePath" => "/path/to/your/log/files/",
	"maxAttempt" => 3
));
```

You can also pass the array directly to `new MappIntelligence()`, `MappIntelligence::getInstance()` and `new MappIntelligenceHybrid()`.

**Config File (ini)**

```php
$mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/config/file/config.ini"
);
```

```plaintext
[tracking]
trackId="111111111111111"
trackDomain="analytics01.wt-eu02.net"
deactivate=false
domain[]="sub.domain.tld"
useParamsForDefaultPageName[]="aa"
useParamsForDefaultPageName[]="bb"
useParamsForDefaultPageName[]="cc"
containsInclude[]=foo
containsInclude[]=bar
containsExclude[]=test
matchesInclude[]=/.*foo.*/
matchesInclude[]=/.*bar.*/
matchesExclude[]=/.*test.*/
; a list can also be one string: domain and useParamsForDefaultPageName are separated with ",",
; containsInclude, containsExclude, matchesInclude and matchesExclude with ";" (a regular expression may contain ",")
; domain = "sub.domain.tld, foo.bar"
; matchesExclude = "/.*test.*/;/\d{1,3}/"

[debugging]
debug=false
logLevel=DEBUG

[consumer]
consumerType="FILE_ROTATION"
filename=""
fileMode="a"
filePath=""
filePrefix=""
maxAttempt=1
attemptTimeout=100
maxBatchSize=50
maxQueueSize=1000
maxFileLines=10000
maxFileDuration=1800000
maxFileSize=25165824
forceSSL=true
```

Entries of a list in the config file are trimmed and empty entries are dropped. The consumer type is case-insensitive (`consumerType = "file"`), an unknown consumer type is ignored. A file that cannot be read or has a syntax error is ignored (defaults are used). Integer values must consist of digits only (no expressions such as `30 * 60 * 1000`), otherwise the value is ignored. `connectionTimeout`, `readTimeout`, `requestInterval`, `requestQueues`, `activateAdvancedPermission` and `advancedPermissionCategory` are not read from the config file; set them with the setters or the config array.