This page explains how to customize Matomo (Piwik) via the config file or a custom PHP bootstrap.php file.

config/config.ini.php: The Matomo Config File

The Matomo (Piwik) installation creates config/config.ini.php. This files overrides the default settings in config/global.ini.php. During Matomo updates this file is never replaced.

You can customize a few settings in this file. For example, the number of rows to be returned by default, proxy configuration, and force SSL for admin access.

See also the How-to FAQs for examples.

bootstrap.php: Execute Custom Code Before Matomo Runs

Matomo (Piwik) will load bootstrap.php if it exists in the top level Matomo folder. This file is not overwritten by subsequent software updates.

You may customize bootstrap.php to contain any legitimate PHP to tailor Matomo (Piwik) to your local requirements, or even perhaps initiate custom code such as a logging process.

You may also use the bootstrap.php file to customize a few Matomo (Piwik) core constants:

  • PIWIK_ENABLE_ERROR_HANDLER – when set to 0, the calling application must implement its own exception/error handler, e.g., try…catch any uncaught exceptions returned by index.php.
  • PIWIK_SESSION_NAME – allows an application to embed Matomo (Piwik) and share session data. The default is ‘PIWIK_SESSID’.
  • PIWIK_ENABLE_SESSION_START – by default (enabled), the Dashboard will initialize and start the session (this has the side-effect of sequentially loading widgets). When calling Matomo (Piwik) from another PHP script which has its own session handling code, or to increase responsiveness (through partial parallel loading), set to 0. Note: this requires more concurrent MySQL connections (see my.cnf’s max_connections).
  • PIWIK_USER_PATH – override the default to relocate config and tmp files outside the web document root. This facilitates a “best practice” of preventing direct access to php files. It is also useful with shared hosting to separate shared code from user/account-specific configuration. The default is the same as PIWIK_DOCUMENT_ROOT. Note: open_basedir() restrictions may apply
  • PIWIK_INCLUDE_PATH – override the default to relocate files loaded by index.php and piwik.php (e.g., via include, include_once, require, and require_once). This facilitates a “best practice” of preventing direct access to PHP files. Default is the same as PIWIK_DOCUMENT_ROOT.

Note: open_basedir() restrictions may apply

Check out the sample bootstrap.php file for inspiration.

Load Matomo PHP classes and Call the API in PHP

Check out the user doc about calling Matomo (Piwik) Rest APIs, either using http requests or using the internal helper classes.

php.ini and .htaccess notes

An overview of PHP and Apache configuration is outside the scope of this document. Care should be exercised when configuring the following:

  • mod_security – to avoid false positives, you’ll need to either disable this extension or exclude Matomo (Piwik)
  • http authentication – ensure that access to piwik.js and piwik.php is not blocked to non-authenticated requests
  • PHP session.auto_start – cannot be used with Matomo (Piwik) as it is incompatible with Zend_Session

Use a custom plugin, or build your own

Browse the Matomo (Piwik) Marketplace to find dozens of different product customisations.

Or build your own plugin or theme!

Any questions?

Many answers and more information about Matomo you can find here:

We are social

Follow us: