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

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

The Piwik installation creates config/config.ini.php. This files overrides the default settings in config/global.ini.php. During Piwik 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 Piwik Runs

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

You may customize bootstrap.php to contain any legitimate PHP to tailor 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 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 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 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 Piwik PHP classes and Call the API in PHP

Check out the user doc about calling 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 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 Piwik as it is incompatible with Zend_Session