Each plugin has its own directory within the root plugins/ directory. Generally, plugins have a similar structure as the Matomo core for most things. Most plugins have only few files, while some others have more files. Below is a list of some files and directories that may exist in a plugin.
| File / Directory | Description |
|---|---|
| .github/ | Contains GitHub related files, like a GitHub test action |
| plugin.json | Contains metadata about the plugin such as contact information, a description, and more. Mostly needed for plugins on the Marketplace. |
| $PluginName.php | $PluginName needs to be replaced with the name of the plugin. This file is the plugin file which allows plugins to listen to events and method hooks such as install(), activate and uninstall(). |
| Activity/ | This directory includes activities that should be logged for the Matomo Activity / Audit Log premium feature. |
| API.php | Defines API methods for this plugin. |
| Archiver.php | This file includes logic on how to create archive reports from log raw data. |
| Categories/ | This directory includes menu categories and subcategories that are used to build the reporting menu. They define for example the order in which they are shown in the menu. |
| changes.json | This optional file contains change notifications which will be displayed on the "What's New?" dialog. |
| Columns/ | This directory includes dimensions and metrics. |
| Commands/ | This directory includes console commands. |
| config/ | This directory can include various files like "config.php" and "test.php" to change Matomo using dependency injection. |
| Controller.php | Defines controller actions for this plugin. |
| Dao/ | This directory includes data access objects that connect mostly to the database and execute queries. It doesn't contain much logic usually. |
| DataTable/Filter | This directory may include custom plugin data table filters. |
| Diagnostic/ | This directory typically includes system checks. |
| docs/index.md | The markdown content of this file will be shown in a Documentation tab on the Marketplace. |
| docs/faq.md | The markdown content of this file will be shown in a FAQ tab on the Marketplace. |
| images/ | This directory includes images and icons that are shown in the user interface. |
| lang/ | This directory includes language files for translations. |
| libs/ | This directory may include third party libraries. Alternatively a node_modules directory can be used. |
| javascripts/ | This directory includes JS files. |
| LocationProvider/ | This directory may include custom location providers. |
| MeasurableSettings.php | Defines custom settings for a measurable / site in Matomo. |
| Menu.php | This file is used to add, remove or change menu entries. |
| Model/ | This directory includes Models. These typically use Dao classes and have more logic. |
| Reports/ | This directory includes reports. One PHP file for each report. |
| screenshots/ | This directory includes screenshots of the plugin, which are then shown on our Matomo Marketplace. |
| Updates/ | This directory includes migration update files. |
| UserSettings.php | Defines user settings which are shown in the personal settings page and can be edited by each user. The setting is stored differently for each user, meaning a change here doesn't affect other users' settings. |
| stylesheets/ | This directory includes CSS or less stylesheet files. |
| SystemSettings.php | Defines system settings which are shown in Matomo's general settings and can be edited by a superuser. |
| Tasks.php | Defines scheduled tasks that are executed periodically similar to a cron. |
| templates/ | This directory includes twig template files. |
| tests/Fixtures/ | This directory includes all kind of fixtures for our automated tests. |
| tests/Framework/Mock | This directory may include PHP mocks used in PHP tests. |
| tests/Integration/ | This directory includes integration PHP tests. |
| tests/javascript/index.php | This file includes JavaScript tests for our JS tracker and Tag Manager. |
| tests/javascript/head.php | This file can be used to load additional JS files in JavaScript tests for our JS tracker and Tag Manager. |
| tests/UI/ | This directory includes UI screenshot tests. Each test file ends with _spec.js. |
| tests/Unit/ | This directory includes unit PHP tests. |
| tests/System/ | This directory includes system PHP tests. |
| tracker.js | If such a file is present, then this code will be added to the Matomo JavaScript tracking code. If a tracker.min.js exists then the minified version will be used. |
| Tracker/RequestProcessor.php | This file is typically used to hook into various events during a tracking request. |
| Tracker/LogTable/ | This directory can include log tables if the plugin creates custom log tables for tracking data. |
| vendor/ | Libraries installed by Composer. |
| VisitorDetails.php | This file is used to add additional information to the visitor log or visitor profile. |
| Visualizations/ | This directory includes visualizations that show report data differently. |
| Widgets/ | This directory includes widgets. One PHP file for each widget. |
