Setting Up

About this guide

If you're a Piwik user and need Piwik to do something it doesn't do; or maybe you use another web app and want to integrate it with this amazing analytics software you've heard so much about (Piwik, naturally) — well, you've come to the right place!

This guide will show you:

  • how to get your development environment setup,
  • how to create a new Piwik Plugin,
  • and where to go next to continue building your extension.

Guide assumptions

This guide assumes that you can code in PHP and can setup your own local webserver. If you do not have these skills, you won't be able to understand this guide.

There are many resources on the internet to help you learn PHP. We recommend reading these tutorials. To learn how to setup a web server read the documentation for your preferred web server software (for example Apache or Nginx).

Piwik Plugins and Piwik Core

All the functionality you see when you use Piwik is provided by Piwik Plugins. The core of Piwik (termed Piwik Core) only contains tools for those plugins.

If you want to add more functionality to Piwik, create your own plugin then distribute it on the Piwik Marketplace so that others can use it.

Note: If you want to integrate another piece of software with Piwik and you only need to know how to track visits or how to retrieve reports, read more about Integrating Piwik in your application.

What is possible with Piwik plugins?

You can accomplish the following by creating a plugin:

  • track new visitor data and create new reports to aggregate it
  • track third party data and display it in new reports
  • show existing reports in a new way
  • send scheduled reports through new mediums or in new formats

These are only a few of the possibilities — it is not possible to categorize all of the existing plugins' functionality simply because of the vast differences in their use cases. For example, the Annotations plugin lets users add notes for dates without requiring modifications to Piwik Core. The DBStats plugin will show users statistics about their MySQL database. The Dashboard plugin provides a configurable way to view multiple reports at once.

Whatever ideas your imagination cooks up, we think you can implement them with Piwik.

Getting setup to extend Piwik

Get the appropriate tools

Before we start extending Piwik, let's make sure you have the tools needed. You will need the following:

  • A PHP IDE or a text editor. We recommend using PhpStorm, a powerful IDE built specifically for developing in PHP.
  • A webserver, such as Apache or Nginx. You can also use PHP's built-in webserver on your development machine if you have PHP 5.4 or higher installed.
  • A MySQL database
  • git so you can work with the latest Piwik source code.
  • Composer so you can install the PHP libraries needed by Piwik.
  • A browser, such as Firefox or Chrome. Ok, you've probably got this.

The following tools aren't required for this guide, but you may find them useful as you create your plugin:

  • PHPUnit Necessary if you want to write or run automated tests.
  • xhprof If you'd like to profile your code and debug any inefficiencies.
  • python If you want to use the log importer.

Command to get the tools on Linux

If your computer is using a Debian based operating system, you can install all the required packages with the following command:

$ sudo apt-get install php7.0 php7.0-curl php7.0-gd php7.0-cli mysql-server php7.0-mysql php-xml php7.0-mbstring

Get & Install Piwik

We'll get the latest version of Piwik's source code using git.

Open a terminal, cd into the directory where you want to install Piwik, and then run the following commands (without the leading $):

$ git clone https://github.com/piwik/piwik piwik
$ cd piwik
$ git submodule update --init

Get & install Composer

Next, we will install all the libraries that Piwik needs using Composer.

  • Follow the download instructions for Composer in order to get composer on your machine

  • Then run this command to download all PHP packages that Piwik requires:

    $ php composer.phar install
    

    On Windows you will likely need to add an option --no-script:

    $ php composer.phar install --no-script
    

Get a web server

Now that you've got a copy of Piwik, you'll need to point your web server to it. If you use Apache or Nginx, the specific instructions for configuring your web server depend on the web server itself.

If your PHP version is greater than 5.4, you can also use PHP's built-in web server which requires no installation. Simply run the following command:

$ php -S 0.0.0.0:8000

Piwik should now be available at http://localhost:8000/. To stop the web server, just hit Ctrl+C. Remember that PHP's built in web server is only suitable for development. It should never be used in production.

Install Piwik

Once Piwik is running, open it in your browser and follow the instructions to complete the installation.

When you install Piwik, at the database creation, you will need to specify your database user. Click here to see how to create a new user in MySQL.

Adding anonymous access to your reports

Before we finish, we're going to allow anyone to view reports on your new Piwik environment. Open the Manage > Users admin page and click the red icon in the View column for the anonymous user:

This will make it possible to view raw report data without having to supply a token_auth.

Enable Development mode

After installing Piwik, we're going to change some of Piwik's INI configuration to make development easier and to make sure all changes take effect immediately. Piwik comes with a handy command-line tool that will do this work for you. In the root directory of your Piwik install, run the following command to enable development mode:

./console development:enable

Add some test tracking data in your Piwik

You're now ready to create your first plugin, but before we do that, let's add some test data for you to play with.

In your browser, load Piwik and navigate to _Administration > Marketplace. Look for the "Visitor Generator" plugin and enable it. Then on the admin menu to the left, click on "Visitor Generator" (under "Development").

On this page you'll see a form where you can select a site and enter a number of days to generate data for:

Let's generate data for three days. Enter 3 in the Days to compute field, check the Yes, I am sure! checkbox and click Submit.

Once the visits have been added, click on the Dashboard link at the top of the screen. You should see that reports which were previously empty now display some statistics:

If you want to execute the automated test suite

If you plan on running automated tests, you'll have to set the following configuration options in config/config.ini.php:

[database_tests]
host = "127.0.0.1"
user = ...
password = ...

You also may have to create the piwik_tests database:

mysql -u'db_username_here' -p -e 'CREATE DATABASE piwik_tests'

Create a plugin

Your development environment is set up, and you are now ready to create a plugin! Creating a plugin consists primarily of creating a couple of files which can be done by running the following command:

./console generate:plugin --name="MyPlugin"

This will create a new plugin named MyPlugin.

You can use any name for your plugin, but this guide will assume you've created one named MyPlugin. If you use a different name, make sure to change MyPlugin to the name you used when copying the code in this guide.

In your browser load Piwik and navigate to Administration > Plugins. Look for your plugin in the list of plugins, you should see it disabled:

To enable it, either do it through the web interface or use the command line:

./console plugin:activate MyPlugin

Plugin directory structure

The command-line tool will create a new directory for your plugin (in the plugins sub-directory) and fill it with some files and folders. Here's what these files and folders are for:

  • MyPlugin.php: Contains your plugin's descriptor class. This class contains metadata about your plugin and a list of event handlers for Piwik events.
  • plugin.json: Contains plugin metadata such as the name, description, version, etc.
  • README.md: A dummy README file for your plugin.
  • screenshots/: Place screenshots of your plugin in this folder in case you want to distribute it on the Piwik Marketplace.

Ok! You've set up your development environment and created your plugin! Now all you have to do is make it do what you want. The bad news is that this is the hard part. The good news is that we've written a bunch of other guides to help you shorten the learning curve.

  • If you're interested in creating new analytics reports, you may want to read about Custom Reports and Visualizing Report Data guides.
  • If you're interested in changing the look and feel of Piwik, read the Theming guide.
  • If you're interested in integrating Piwik with another technology, you might want to read the Tracking guides to learn how to use the Tracking API.
  • If you want to use automated testing to ensure your plugin works, read the Automated Tests guide.

And make sure to read our security guide, Security in Piwik! We have very high security standards that your plugin or contribution must respect.

When you've completed your plugin, you can read the Distributing your plugin guide to learn how to share your plugin with other Piwik users.