Include & Customize Matomo for your Project

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 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 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 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 core constants:

  • PIWIK_PRINT_ERROR_BACKTRACE – when set to 1, any error or uncaught exception will also display the backtrace leading to the error (useful when creating bug report, or troubleshooting an error).
  • 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 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 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

Call the API in PHP

Check out the user doc about calling Matomo Rest APIs using https requests.

Use a custom plugin, or build your own

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

Or build your own plugin or theme!

Previous FAQ: How do I change the default email address “From:” in password reset emails?