Contributing to Matomo (formerly Piwik) Core

About this guide

Read this guide if

  • you've found a bug, fixed it and want to know how to get your fix accepted upstream
  • you're interested in contributing changes to Matomo and want to know where to start or want to know what the process is like
  • you'd like to know what Matomo developers consider to be good code

Guide assumptions

This guide assumes that you:

  • can code in PHP and JavaScript,
  • can use the git source code management tool
  • are familiar with GitHub,
  • and have the necessary tools to contribute to Matomo (if not, see this section of our Getting started extending Matomo guide).

Contribution process

The contribution process starts with a bug you want to fix or an idea that you want to implement. If you don't have one, feel free to pick an open ticket on

Once you've decided on something, continue below.

Getting a copy of Matomo to work on

Before you can start contributing you need to get setup with git & GitHub. If needed, you can create a GitHub account here.

Fork the Matomo repository

While logged in GitHub, visit Piwik's repository. In the upper right corner there is a Fork button. Click it. Github will copy the repository into your account. This copy (or fork) is the one you will work on. If you don't know forks, read more about forks on GitHub.

Setup git

When committing, git will need to know your username and email. To set them, run the following commands:

git config --global John Doe
git config --global

Clone the forked repository

Clone your Matomo fork (replace myusername with you GitHub user name):

git clone

This will copy the entire forked repository (including all history) to the piwik folder on your machine.

Now, we'll run one more command so git remembers the original Matomo repository in addition to your fork:

git remote add upstream

This will save as a remote and name it upstream.

Configure PHP

Contributions should not generate PHP errors or warnings. Applying the following settings to your php.ini file will enable you to catch these errors:

display_errors  = On
error_reporting = E_ALL | E_STRICT

Hacking Matomo

Now that you have a copy of the latest Matomo source code, you can start modifying it. For this section, we'll assume there's a bug that you found and want to fix.

Create a new branch

Before you start coding, you should make sure to keep your changes separate from the 3.x-dev branch. This will make it much easier to track the changes specific to your feature since your changes won't be mixed with any new commits to the 3.x-dev branch from other developers.

We'll give our new branch a name, bugfix, that describes what we're doing, so we can recognize it later. To add a new branch, run the following command:

git checkout -b bugfix

The checkout command will create a new branch if the -b option is supplied, otherwise it will try to load an existing branch.

Work on the code

Once you've created a branch, you have a place to start working on the feature. There's nothing special about this part of the process, just fix the bug or finish the feature you're working on.

If you're working on something more complex than a bugfix, you may have the need to keep your new branch updated with changes from the main repository. Keeping your branch up to date is a two-step process.

First, on your 3.x-dev branch, pull changes from the main Matomo repository, nicknamed upstream:

git pull upstream 3.x-dev

Then, on your new branch (bugfix for this tutorial), merge with 3.x-dev:

git merge 3.x-dev

If there are conflicts, you can read this guide: How to resolve Git conflicts.

Save your changes

Now that you've finished the bug fix or new feature (or just part of it), it's time to commit your changes and push them to your fork (the origin remote).

git add ModifiedFile.php AnotherFile.js
git commit -m'Added new feature: XYZ (replace this with a descriptive commit message)'
git push

You can read this guide to learn how to commit changes. You can read this guide to learn how to push commits.

Creating a pull request

Now that your changes are published, you can send them in a pull request to the main Matomo project.

To do so, visit your fork on GitHub and select the bugfix branch in the branch selector (located right above the directory listing on the left side of the page). Then click the Pull Request button in the middle of the top of the page.

On this screen you'll be able to see exactly what changes you've made by looking at your commits and at what files have been changed. You can use this as an opportunity to review your changes.

Read Creating Pull requests: best practises to maximise your changes to create a great pull request.

Once you're ready to create the pull request, write a description of the pull request and any notes that are important for the person who will review your code, and then click Send pull request. This will create a new pull request which you will be able to find and view here.

Updating the pull request

Once your pull request is public, developers will review it and leave comments regarding what should be changed. You can then make changes, commit them and then push them to your remote repository (origin) and they will automatically be shown in the pull request.

Creating Pull requests: best practises

Here are best practises we aim to follow when creating, reviewing and merging pull requests:

  • We try to avoid big pull requests and aim for small PRs that are easier to review
  • When issuing a PR we set a label Pull Request WIP and replace this label with Needs Review once the PR is done. If a PR references another issue we assign the label not-in-changelog
  • A PR should contain a description explaining things if useful. It should contain as much as necessary and as little as possible.
  • Small changes can be merged directly without a review if the developer is 100% certain the change won't have any side effects etc. It is still always recommended to quickly ask another developer that is online to have a look at this PR now as such PRs are quickly reviewed.
  • If a PR affects the public API in any way a PR should not be merged without a review
  • PRs that affect the public API or that affect Security need a thorough review. For other PRs it is always good to keep in mind that we can change later at anytime. Things therefore don't have to be "perfect" as long as the formal requirements are given (eg. an entry in the developer changelog if needed)
  • When reviewing a PR it is important to check things like Security, Performance, Usability, etc. Minor "issues/feedback" such as feedback on code style are less important. If a reviewer notices only such minor things, we can merge the PR directly or the reviewer can make the changes directly and merge afterwards.
  • Before working on a new issue it is recommended to check for pending PRs that have a Needs Review label
  • PHP code should use our Matomo code standards (see next section)
  • Pull requests should contain tests
  • Read the article: Pull Requests: How to Get and Give Good Feedback
  • When a pull request has many small commits, it is recommended to Squash commits so that there is only one (bigger) commit.

Matomo Core code standards

The following are a list of guidelines and requirements for contributions to Matomo Core. Developers and teams interested in contributing should read through them before starting to contribute and before sending a pull request. Contributions that are not up to these standards will not be accepted.

General Considerations

  • Write clear, easily understandable code. Is your code easy to read? Would anybody understand what each line and function does immediately after reading them? Code that does not do anything complicated should be this easy to understand. Complex code should have extra documentation that will aid new developers in understanding it.

  • Reuse as much code as possible. Have you removed any redundancies in your code? Have you made sure your code does not replicate existing functionality? Try to reduce the amount of code you need to write for your contribution.

  • Write correct code. Does your code handle all possible scenarios? Does your code handle all possible error conditions (including any corner cases)? Do existing tests pass for your contribution? Does your code generate any unwanted PHP errors or warnings? We do not want contributions that introduce new bugs.

  • Write efficient code. Does your code scale well? What happens when there are hundreds of thousands of websites and billions of visits? Please note any potential performance issues and whether they would be easy to fix. We know how hard it can be to scale efficiently, but we would like for Matomo to be as fast as possible.

  • Follow our security guidelines. We do not allow any security vulnerabilities in contributions.

Specific Considerations

  • Add new configuration settings for fixed values that may users may change. Does your code use constants that users may want to change? They should be made configurable.

  • Use automated testing to test your PHP. If you've written new PHP code, have you created unit and integration tests for them? All code that could benefit from automated tests should have tests written for them. Read our Testing guide to learn about it.

  • Internationalize your text. If your contribution has text, is it loaded from a language file? We want all text in Matomo Core to be available in as many languages as possible. To learn more about i18n in Matomo read our Internationalization guide.

  • Generate HTML in template files only. Does your PHP code contain HTML? It shouldn't. All HTML generation should be handled by Twig templates.

  • If your contribution includes third-party components & libraries, make sure they include GPL compatible licenses. Third-party components/libraries must be compatible with GPL v3 since this is the license used by Matomo.

  • Make sure your code follows the PSR 1, PSR 12 and PSR-4 coding standards.

  • Make sure your source code files are encoded in UTF8.

  • Make sure lines end with Linux EOL markers (LF). To learn how to let git manage line endings for you, read this.

Coding Considerations

The following are a list of guidelines you should follow while writing code and architecting software.

Include Path

Matomo does not set or depend on the include path. Plugins should rely on the autoloader for classes and use the absolute path convention for other files:

require_once PIWIK_INCLUDE_PATH . '/folder/script.php';

Basic Clean Code recommendations

About classes:

  • Classes should follow the Single Responsibility Principle.
  • Refactor classes and aim for files/classes that are at most 400 lines.
  • Avoid classes with both public attributes and getters/setters. Choose to use getters and setters only when they make code easier to read.
  • Add private keywords to class attributes when forgotten.

About methods and functions:

  • Functions should follow the Single Responsibility Principle: each function should do only one thing.
  • Think about whether you can refactor the function body into smaller private methods.
  • Aim for a maximum of 20-30 lines per method.
  • Aim for maximum three function parameters.
  • Extract the body of the try {} blocks into their own private method.

Keep the following principles (from Alan Shalloway) in mind while writing code: cohesion, loose coupling, no redundancy, encapsulation, testability, readability, and focus.


In order for new developers to get up to speed quickly and in order to lessen the amount of bugs Matomo will ever experience, the Matomo source code must be easy to understand. Comments, in addition to general code cleanliness, are important in achieving this goal.

Comments are a central part of professional coding. Comments can be divided into three categories: documentary (serving the purpose of documenting the evolution of code over time), functional (helping the co-ordination of the development effort inside the team) and explanatory (generating the software documentation for general use). All three categories are vital to the success of a software development project.

The fine Art of Commenting

For an example of a well commented Matomo class, see Piwik\Cookie.

Despite their importance, comments can sometimes cause information overload - or worse for out-of-date comments. Useless or inaccurate comments and autogenerated comments that add no value should be avoided. Rather than writing comments inside a function, it is better to write shorter functions that do only one thing and are named thoughtfully. A well refactored class made of small methods will be easy to read and will not need many comments.

No duplication

No duplication is a basic and core principle of extreme programming and of writing good code in general. Write code "Once, and only once", i.e. Don't Repeat Yourself. Do not duplicate code.

Debugging & logging

In Matomo you can easily log debug messages to files, the database or the screen by enabling logging in your config/config.ini.php file. In your code, you can then call one of the Log singleton's logging methods to log new messages.

You can also show the debug output on screen by appending &debug=1 to the URL: this allows you to test and view debug messages only when needed, but still leave debug logging enabled. See the FAQ to enable logging output in Matomo and the various options.

Matomo comes with a SQL profiler, which reports the time spent by each query, how many times they were called, the total time spent in MySQL vs PHP, etc. It makes it easier to check the performance and overhead of your new code. See the FAQ to learn how to enable SQL profiling.

Automated tests

If you are fixing a bug, it is usually better to also submit a testcase covering this fix. Such a test will be useful to prevent the bug from reappearing again in the future.

If you are adding a new feature to Matomo, adding a new API method or modifying a core Archiving or Tracking algorithm, generally it is required to also submit new or updated unit or integration tests.

For more information about running or creating tests, read our Testing guide.

When naming unit/integration tests, it helps to use the Given, When, Then convention for writing tests.

Tests are critical part of ensuring Matomo stays a stable and useful software platform. We aim to keep test code as clean as production code so it is easy to improve and maintain.

Submitting a plugin for integration into Core

If you've already developed a plugin (congratulations!) which you think could be included in Matomo Core, you can offer it for inclusion.

The adoption of a plugin into Matomo Core requires that we consider such criteria as (but not limited to):

  • audience: plugin appeals to a broad spectrum of users
  • desirability: is it a frequently requested feature by the Matomo community?
  • functionality: feature completeness
  • testability: use of unit, integration and UI tests and impact to manual testing (e.g., differences when plugin is activated vs deactivated)
  • maturity: history and popularity of the plugin
  • performance: impact on archiving and/or UI interaction
  • supportability: likelihood of spawning support tickets and forum posts of the "how do I?" or "why does it?" variety
  • complexity: simpler is better; +1 if developer has git commit privileges
  • dependencies: does it depend on closed source and/or paid subscription services?
  • licensing: license compatibility with GPLv3

In most cases, it should be enough for your plugin to be available on the Marketplace.

Learn more