This is the Developer Changelog for Matomo platform developers. All changes in our HTTP APIs, Plugins, Themes, SDKs, etc. are listed below.
The Product Changelog at matomo.org/changelog lets you see more details about any Matomo release, such as the list of new guides and FAQs, security fixes, and links to all closed issues.
Matomo now supports providing authentication using Bearer header tokens. Instead of sending your auth token as GET or POST param, you can use a header like Authorization: Bearer myAuthToken.
The ImageGraph URLs returned by some of our APIs do no longer contain the token_auth. If you are using such URLs to e.g. directly fetch their content, you may need to adjust your implementation to append a valid token_auth again.
The new API parameter showMetadata was introduced. In can be used to toggle displaying of metadata in API exports. The default value is 1 to keep current behavior.
setIgnoreCampaignsForReferrers and getIgnoreCampaignsForReferrers have been added to the JavaScript tracker. They allow to set/get referrers for which campaign parameters should be ignored. For more details see Configuration of JavaScript tracker documentation.Goals.getGoals, the result will no longer be indexed by idgoal. Requesting the goals for a single site will still return them indexed by idgoal.Google indexed pages. As Google search is no longer accessible without JavaScript this metric can no longer be fetched.getNthLevelTableDimension has been added to the Report class. This extends support for subtable reports for more than three levels.getSystemSignalsToHandle function in the command implementation. This feature is gated behind the "SystemSignals" feature flag, signal subscription will be silently disabled unless that feature flag is enabled.Report::getThirdLeveltableDimension has been deprecated. Use Report::getNthLevelTableDimension(2) instead.core:reset-invalidations allows administrators to reset stuck invalidations that are incorrectly marked as "in progress".previous_Actions_nb_pageviews => previous_nb_pageviewsprevious_Goal_revenue => previous_revenueprevious_Goal_nb_conversions => previous_nb_conversionsprevious_Goal_0_nb_conversions => previous_ordersprevious_Goal_0_revenue => previous_ecommerce_revenueDb::isOptimizeInnoDBSupported, Db::optimizeTables have been deprecated. Use Db\Schema::getInstance()->isOptimizeInnoDBSupported and Db\Schema::getInstance()->optimizeTables insteadTransactionLevel::setUncommitted has been deprecated. Use TransactionLevel::setTransactionLevelForNonLockingReads insteadPiwik\Plugins\SitesManager\API::setGlobalExcludedQueryParameters has been deprecated. Use Piwik\Plugins\SitesManager\API::setGlobalQueryParamExclusion insteadplugin:install-or-update lets you install or update a plugin from the Marketplace.errorlog (\Monolog\Handler\ErrorLogHandler) and syslog (\Monolog\Handler\SyslogHandler) handlers are no longer directly used. Plugins using or overwriting those handlers using DI should now use the scoped classes Piwik\Plugins\Monolog\Handler\ErrorLogHandler and Piwik\Plugins\Monolog\Handler\SyslogHandler instead.jQuery.dotdotdot has been removed. Please use pure CSS instead or include the library in your plugin if needed.The API method Overlay.getExcludedQueryParameters has been deprecated and will be removed in Matomo 6. Use the new method SitesManager.getExcludedQueryParameters instead.
disableCampaignParameters have been added to the JavaScript tracker. It allows to disable processing of campaign parameters and forwarding them to the tracking endpoint.Common::fixLbrace() function has been removed. It was only necessary for AngularJS and no longer needs to be used.JSON2 API format has now been removed. We recommend switching to the JSON renderer, which behaves the same.piwikPageChange, which is triggered when a reporting page is loaded, has been renamed to matomoPageChange. Ensure to update your implementation if you rely on it.broadcast.init, broadcast.propagateAjax and broadcast.pageLoad have been removed.instance_id configuration does no longer support characters other than a-z, 0-9 and the special characters .-_. If the configured value contains other characters, they will be simply removed.file:// protocol is no longer tracked. To enable tracking of the file:// protocol use the new JavaScript tracker method enableFileTracking (learn more).proxy_ip_read_last_in_list = 0.Piwik\Log::setLogLevel() has been removedPiwik\Log::getLogLevel() has been removed$login has been added to the methods setCompleted(), isCompleted(), skipChallenge() and isSkipped() in the Piwik\Plugins\Tour\Engagement\Challenge classPiwik\Log\Logger instead of Monolog\LoggerPiwik\Log\LoggerInterface instead of Psr\Log\LoggerInterfacePiwik\Log\NullLogger instead of Psr\Log\NullLoggerPiwik\DI instead of DIDI namespaced functions need to be replaced with static Piwik\DI methods. E.g. DI\add() will become Piwik\DI::add()Piwik\Exception\DI\DependencyException or Piwik\Exception\DI\NotFoundException\Piwik\Container\Container where you used to use \Psr\Container\ContainerInterface or DI\Container as typehintsPiwik\Plugins\ConsoleCommand has been rewritten. To migrate your commands you need to apply some changes:run, execute, interact or initialize can no longer be overwritten. Instead, use our custom methods prefixed with do: doExecute, doInteract or doInitialize
doExecute() method needs to return integers. We recommend using the class constants SUCCESS or FAILURE as return values.$this->getInput() or $this->getOutput() instead. Don't use InputInterface or OutputInterface as method typehints.addOption and addArgument can no longer be used
addOptionalArgument or addRequiredArgumentaddNegatableOption, addOptionalValueOption, addNoValueOption or addRequiredValueOptionaskForConfirmation, askAndValidate or askinitProgressBar, startProgressBar, advanceProgressBar and finishProgressBarrenderTablerunCommandHTTP_X_FORWARDED_FOR header containing the current user's IP address. If you use an outbound proxy rule that used this header to allow access for Matomo then it should be replaced with rule allowing access by IP and/or URL.Piwik\Request has been introduced. It will allow fetching parameters from a request, optionally validated / casted to a certain type. Use this class in favor of Common::getRequestVar.$autoSanitizeInputParams. Setting this variable to false will prevent an automatic apply of Common::sanitizeInputValues on all parameter passed to the API methods. By now this property defaults to true, but this might change in upcoming major releases.Common::getRequestVar is now deprecated, but will remain API until Matomo 6. You may already start using the new class Piwik\Request instead, but ensure to handle needed sanitizing / escaping yourself.color-black-piwik, color-blue-piwik, color-red-piwik and color-green-piwik are now deprecated and will be removed in Matomo 6. New variables where piwik was replaced with matomo have been introduced. E.g. color-black-matomoenable_segments_subquery_cache INI config, has been removed. Segment SQL queries that reference actions now directly join log_action. Related INI config options segments_subquery_cache_ttl and segments_subquery_cache_limit have also been removed.Archiving.getIdSitesToMarkArchivesAsInvalidated started passing date, period ,segment and name parameter along with idSites parameter.--concurrent-archivers parameter can be used to increase this limit. A value of -1 will use an unlimited number of concurrent archiversonly_allow_secure_auth_tokens, defaulting to 0, has been added. Enabling this option will prevent any use of tokens in GET API requests._rcn and _rck are no longer used to attribute visits. Those parameters will now only be used to attribute conversions. If you want to manually attribute a visit to a campaign ensure to attach campaign parameters to the tracked URL instead.ssl_disallow_self_signed ,ssl_verify_peer, ssl_verify_peer_name under [mail] to allow modifying the SSL handling in SMTP request.enable_opcache_reset defaulting to 1. Provides a configuration switch for opcache_reset when general caches are cleared. This may be useful for multi-tenant installations that would rather manage opcache resets by themselves. This could also be used by scripts to temporarily switch off opcache resets.UsersManager.deleteUser API using a session authentication, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.UsersManager.addUser API using a session authentication, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.UsersManager.inviteUser API using a session authentication, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.Login.userRequiresPasswordConfirmation, which can be used in login plugins to circumvent the password confirmation in UI and for certain API methodsSitesManager.deleteSite API using a session authentication, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.setExcludedReferrers and getExcludedReferrers have been added to the JavaScript tracker. They allow setting and receiving the referrers the JavaScript tracker should ignore. If a referrer matches an entry on that list, it will not be passed with the tracking requests and the attribution cookie will stay unchanged. This can for example be used if you need to forward your users to an external service like SSO or payment and don't want any visits or conversions being attributed to those services.force_matomo_http_request defaulting to 0. If the Matomo instance can't make requests to matomo.org via HTTPS this can be set to 1 to force matomo marketplace and matomo api requests to use HTTP instead of HTTPS.UsersManager.inviteUser.end, which is triggered after a new user has been invitedUsersManager.inviteUser.resendInvite, which is triggered after the invitation to a user has been resentUsersManager.inviteUser.accepted, which is triggered after an invitation has been acceptedAdded new event UsersManager.inviteUser.declined, which is triggered after an invitation has been declined
The existing event UsersManager.addUser.end will only be triggered when a user is added using the API.
plugin.json might reveal version details, json files will now longer be considered as static files that can be served safely. Therefore json will no longer be included in the list of static file extensions in generated .htaccess files.enable_default_location_provider in Tracker has been added. By setting this option to 0, you can disable the default location provider. This can be used to prevent the geolocator to guess the country based on the users language, if the configured provider doesn't provide any results.Segment.filterSegments. Plugins can use this to filter segment definitions.piwik-field and related directives have been converted to Vue and the template-file attribute is now considered deprecated and will be removed in Matomo 5. Instead,
the component property should be used to add a new form field, it should be an object with two properties that reference a Vue component, plugin and name, where plugin
is the plugin the Vue component is located in and name is the Vue name of the component's export.SecurityPolicy.addPolicy, SecurityPolicy.overridePolicy, SecurityPolicy.removeDirective, SecurityPolicy.allowEmbedPage, SecurityPolicy.disable allow developers to modify or disable the default Content Security Policy. Plugins\Controller has a new member securityPolicy so plugins can use $this->securityPolicy to access these new methods when a custom Content Security Policy is needed.npx browserslist will list the browsers currently supported.totalEcommerceRevenue, totalEcommerceConversions, totalEcommerceItems, totalAbandonedCartsRevenue, totalAbandonedCarts and totalAbandonedCartsItems.contact_email_address in General has been added. It will be used as contact email address for users. If not defined (default) all email addresses of all super users will be used instead, which equals the behavior it used to be.logme method for automatic logins is now disabled by default for new installations. For existing installations it will be enabled automatically on update. If you do not need it please consider disabling it again for security reasons by setting login_allow_logme = 0 in General section of config.ini.php.url param for the automatic login action logme, will no longer do redirects to untrusted hosts. If you need to do redirects to other URLs on purpose, please add the according hosts as trusted_hosts entry in config.ini.php[General] proxy_ip_read_last_in_list be set to 1. Using the last IP can be more secure when you are using proxy headers in combination with a load balancer.core:version which returns the Matomo version number.core:create-security-files which creates some web server security files if they haven't existed previously (useful when using for example Apache or IIS web server).enableLinkTracking did not follow the DOM changes, from this version when the DOM updates, Matomo automatically adds event listeners for new links on the page. It makes it easier to track clicks on links in SPAs. From this version, if we use the addListener method to add event listener manually after the DOM has changed and the enableLinkTracking is turned on we will track the click event for that element twice.password_hash_algorithm, password_hash_argon2_threads, password_hash_argon2_memory_cost and password_hash_argon2_time_cost INI config options have been added to allow using specific password_hash algorithms and options if desired.enable_php_profiler INI config option was added. This must now be set to 1 before profiling is allowed in Matomo.geolocation_download_from_trusted_hosts was introduced. Downloading GeoIP databases will now be limited to those configured hosts only.login_password_recovery_email_address and login_password_recovery_name have been removed to avoid possible smtp problems when sending recovery mails. noreply_email_address and noreply_email_name will be used instead.JSON object in the JavaScript tracker. This means IE7 and older, Firefox 3 and older will be no longer suppported in the tracker.sendBeacon by default if supported by the browser. You can disable this by calling the tracker method disableAlwaysUseSendBeacon. As a result, callback parameters won't work anymore and a tracking request might not appear in the developer tools. This will improve the load time of your website. Tracking requests will be sent as POST request instead of GET but the parameters are by default included in the URL so they don't go lost in a redirect.PiwikInitialized has been renamed to MatomoInitializedmatomoPluginAsyncInit instead of piwikPluginAsyncInitsetVisitStandardLength has been removed as there is no need for it anymore.setGenerationTimeMs(generationTime) has been removed as the performance API is now used. Any calls to this method will be ignored. There is currently no replacement available yet.getPiwikUrl has been deprecated and getMatomoUrl should be used instead.piwikAsyncInit has been deprecated and matomoAsyncInit should be used instead.window.Piwik has been deprecated and window.Matomo should be used instead.These are only recommendations (because we will keep backward compatibility for many more years), but we do recommend you update your code for consistency and for future proofing your tracking:
piwik_ignore css class to ignore outlinks we recommend replacing it with matomo_ignorepiwik_download css class to mark a link as download we recommend replacing it with matomo_downloadpiwikTrackContent, piwikContentPiece, piwikContentTarget, and piwikContentIgnoreInteraction with matomoTrackContent, matomoContentPiece, matomoContentTarget, and matomoContentIgnoreInteraction.matomo.js JS tracker file instead of piwik.js and matomo.php tracker endpoint instead of piwik.php endpoint.getMatomoUrl has been added which replaces getPiwikUrl.JSON2 API format has now been deprecated and is now applied by default. The JSON2 renderer will be removed in Matomo 5 and we recommend switching to the JSON renderer.JSON renderer now behaves like the previous JSON2 renderer did. This means arrays like ['a' => 0, 'b' => 1] will be rendered in JSON as {"a":0,"b":1} instead of [{"a":0,"b":1}]. This impacts these API methods:
php has been removed.API.getBulkRequest may change if the API returns a scalar value (eg 5). In this case the response will be no longer 5 but for example {value: 5}UsersManager.getTokenAuth has been removed. Instead you need to use UsersManager.createAppSpecificTokenAuth and store this token in your application.UsersManager.createTokenAuth has been removed. Instead you need to use UsersManager.createAppSpecificTokenAuth and store this token in your application.DevicesDetection.getBrowserFamilies has been removed. Instead you need to use DevicesDetection.getBrowsersCustomPiwikJs.doesIncludePluginTrackersAutomatically has been renamed to CustomJsTracker.doesIncludePluginTrackersAutomaticallyLive.getLastVisitsForVisitor has been removed. Use Live.getVisitorProfile instead.Live.getLastVisits has been removed. Use Live.getLastVisitsDetails instead.API.getDefaultMetricTranslations, API.getLogoUrl, API.getHeaderLogoUrl, API.getSVGLogoUrl, API.hasSVGLogoSitesManager.getSitesIdWithVisits, SitesManager.isSiteSpecificUserAgentExcludeEnabled, SitesManager.setSiteSpecificUserAgentExcludeEnabledReferrers.getKeywordsForPageUrl and Referrers.getKeywordsForPageTitle. Use Referrers.getKeywords instead in combination with a entryPageUrl or entryPageTitle segment.alias from the API methods UsersManager.addUser and UsersManager.updateUser has been removed.ca has been added which can be used for tracking requests that aren't page views see #16569Db.getTablesInstalled, plugins should use to register the tables they create.CustomPiwikJs.piwikJsChanged has been renamed to CustomJsTracker.trackerJsChangedCustomPiwikJs.shouldAddTrackerFile has been renamed to CustomJsTracker.shouldAddTrackerFileCustomMatomoJs.shouldAddTrackerFile has been renamed to CustomJsTracker.manipulateJsTrackerLive.getAllVisitorDetails has been removed. Use a VisitorDetails class instead (see Live plugin).Live.getExtraVisitorDetails' has been removed. Use the VisitorDetails class within each plugin instead.Piwik.getJavascriptCode has been renamed to Tracker.getJavascriptCode.LanguageManager.getAvailableLanguages has been removed. Use LanguagesManager.getAvailableLanguages instead.$completed parameter for the 'CronArchive.archiveSingleSite.finish' event has been removed. For both this event and the CronArchive.archiveSingleSite.start event, a new
parameter is added for the process' pid. Multiple processes can now trigger this event for the same site ID.\Piwik\Plugin::getListHooksRegistered() has been removed. Use \Piwik\Plugin::registerEvents() instead\Piwik\Piwik::doAsSuperUser() has been removed. Use \Piwik\Access::doAsSuperUser() instead\Piwik\SettingsPiwik::isPiwikInstalled() has been removed. Use \Piwik\SettingsPiwik::isMatomoInstalled() instead\Piwik\Updates::getSql() has been removed. Use \Piwik\Updates::getMigrations() instead\Piwik\Updates::getMigrationQueries() has been removed. Use \Piwik\Updates::getMigrations() instead\Piwik\Updates::executeMigrationQueries() has been removed. Use \Piwik\Updates::executeMigrations() instead\Piwik\Updates::update() has been removed. Use \Piwik\Updates::doUpdate() instead\Piwik\Updater::updateDatabase() has been removed. The method is not needed anymore.\Piwik\Common::json_encode() has been removed. Use json_encode() instead\Piwik\Common::json_decode() has been removed. Use json_decode() instead\Piwik\Common::getContinentsList() has been removed. Use \Piwik\Intl\Data\Provider\RegionDataProvider::getContinentList() instead\Piwik\Common::getCountriesList() has been removed. Use \Piwik\Intl\Data\Provider\RegionDataProvider::getCountriesList() instead\Piwik\Common::getLanguagesList() has been removed. Use \Piwik\Intl\Data\Provider\LanguageDataProvider::getLanguagesList() instead\Piwik\Common::getLanguageToCountryList() has been removed. Use \Piwik\Intl\Data\Provider\LanguageDataProvider::getLanguageToCountryList() instead\Piwik\Site::getCurrencyList() has been removed. Use \Piwik\Intl\Data\Provider\CurrencyDataProvider::getCurrencyList() instead\Piwik\Piwik::setUserHasSuperUserAccess() has been removed. Use \Piwik\Access::doAsSuperUser() instead\Piwik\MetricsFormatter has been removed. Use Piwik\Metrics\Formatter or Piwik\Metrics\Formatter\Html instead\Piwik\Registry has been removed. Use \Piwik\Container\StaticContainer instead\Piwik\TaskScheduler has been removed. Use \Piwik\Scheduler\Scheduler instead\Piwik\DeviceDetectorFactory has been removed. Use \Piwik\DeviceDetector\DeviceDetectorFactory instead\Piwik\ScheduledTask has been removed. Use \Piwik\Scheduler\Task instead.\Piwik\Translate has been removed. Use \Piwik\Translation\Translator instead.\Piwik\Plugins\Login\SessionInitializer is no longer considered API as it is no longer needed.\Piwik\Container\StaticContainer still exists but we no longer consider it an API and constructor injection should be used instead where possible.Piwik\Columns\Dimension::factory has been removed. Use DimensionsProvider::factory instead.Piwik\Config::reset has been removed. Use the reload method instead.Piwik\Config::init has been removed. Use the reload() method instead.Piwik\Db::getColumnNamesFromTable has been removed. Use the TableMetadata::getColumns method instead.Piwik\Session\SessionInitializer::getHashTokenAuth has been removed. There is no need for this method anymore.Piwik\Tracker::getDatetimeFromTimestamp has been removed. Use Piwik\Date::getDatetimeFromTimestamp instead.Dimension::addSegment() has been removed. See new implementation of DimensionSegmentFactory::createSegment for a replacementPiwik\Plugins\Goals\API::NEW_VISIT_SEGMENT has been removed. Use Piwik\Plugins\VisitFrequency\API::NEW_VISITOR_SEGMENT instead.Dimension::configureSegments() has been changed. Similar to configuring Metrics it now takes two parameters SegmentsList $segmentsList and DimensionSegmentFactory $dimensionSegmentFactory.Segment.addSegments has been changed. It now has one parameter SegmentsList $list, which allows adding new segments to the listCustomPiwikJs has been renamed to CustomJsTrackerPiwik\Plugins\CustomPiwikJs\TrackerUpdater has been renamed to Piwik\Plugins\CustomJsTracker\TrackerUpdaterPiwik\Cookie::set no longer accepts an array as valueZend_Validate and all subclasses have been completely removed.Piwik\Mail) has been rewritten:
Piwik\Mail is now an independet class.\Piwik\Mail\Transport and can be replaced using DI.Piwik\Mail have been removed or changed their signature.UsersManager.createAppSpecificTokenAuth has been added to create an app specific token for a user.Common::hashEquals has been added for timing attack safe string comparisons.hideColumns recursively to nested values by setting hideColumnsRecursively=1. For all Live api methods this is the default behaviour.[General] enable_framed_allow_write_admin_token_auth is set. This means if you currently rely on this functionality, you will need to update your matomo config when updating to Matomo 4. Alternatively, create a user with view access and use the token of this user to embed the report.misc/log-analytics now supports Python 3 (3.5, 3.6, 3.7 or 3.8), it will no longer run with Python 2. If you have any automated scripts that run the importer, you will have to change them to use the Python 3 executable instead.piwik font was removed. Use matomo font instead--piwik-domain has been removed. Use --matomo-domain insteadProxy.redirect has been removed. Instead link to the URL directly in HTML and set an attribute rel="noreferrer noopener"log_link_visit_action column interaction_position has been renamed to pageview_position. If your database queries rely on the column you can simply replace the name.matomo_campaign / mtm_campaign and campaign keyword parameter matomo_kwd / mtm_kwd\DI\object() has been removed. You can use \DI\autowire() or \DI\create() instead.\DI\link() has been removed. Use \DI\get() instead.\DI\value(), unless they are a factory.host_validation_use_server_name = 0, if set to 1, Matomo will prefer using SERVER_NAME variable over HTTP_HOST. This can add an additional layer of security, as SERVER_NAME can't be manipulated by sending custom host headers when configured correctly.The following new JavaScript tracker methods have been added:
_paq.push(['setVisitorId', visitorId]);. This can be used to force a specific visitorId. It takes a 16 digit hexadecimal string._paq.push(['requireCookieConsent']);. Call this method if cookies should be only used when consent was given._paq.push(['rememberCookieConsentGiven']);. Call this method when a user gives you cookie consent._paq.push(['forgetCookieConsentGiven']);. Call this method when a user revokes cookie consent._paq.push(['setCookieConsentGiven']);. Call this method to let the tracker know consent was given for the current page view (won't be remembered across requests).userLogin in the UsersManager.getUserPreference method is now optional and defaults to the currently authenticated user login.ArchiveProcessor.ComputeNbUniques.getIdSites was added so plugins can change which site IDs should be included when processing the number unique visitors and users for a specific site.\Piwik\Plugins\SitesManager\isSiteSpecificUserAgentExcludeEnabled() and \Piwik\Plugins\SitesManager\setSiteSpecificUserAgentExcludeEnabled() have been deprecated.\Piwik\SettingsServer::isMatomoForWordPress() has been added so plugins can detect if the plugin is being executed within Matomo for WordPress or Matomo On-PremisesetVisitStandardLength which lets you configure a custom visit standard length in case a custom "visit_standard_length" is configured in the config. Setting only applies when heart beat is enabled.Metrics.isLowerValueBetter so plugins can define if lower metric values are better for additional metrics.Visualization.beforeRender, triggered after immediately before rendering a visualization.Http.sendHttpRequest and Http.sendHttpRequest.end so plugins can listen to external HTTP requests, monitor them, or resolve the request themselves.CliMulti.supportsAsync so plugins can force or disable the usage of archiving through the CLIUsersManager.setSuperUserAccess API, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.setCustomDimension are now URL encoded (they previously weren't). If you were manually URL encoding the custom dimension values before calling setCustomDimension, your custom dimension values appearing in reports and Visits log/Visitor profile may now be double URL encoded. To solve the double encoding issue, you can remove your URL encoding and trust that Matomo JavaScript Tracker will URL encode the values correctly.ping has been added to send a ping request manually instead of using the heart beat timer.ViewDataTable.configure.end, triggered after view configuration properties have been overwritten by saved settings and query parameters.Referrers.getKeywordsForPageUrl and Referrers.getKeywordsForPageTitle APIs have been deprecated and will be removed in Matomo 4.0.0tmp/logs/matomo.log instead of tmp/logs/piwik.log. This log file path can be edited in your config/config.ini.php in the INI setting logger_file_path.MATOMO_PLUGIN_DIRS or a $GLOBALS['MATOMO_PLUGIN_DIRS'] variable in $MATOMO_ROOT/bootstrap.php.Piwik\Plugin\Manager::getPluginsDirectories() and Piwik\Plugin\Manager::getPluginDirectory($pluginName) have been added as it is now possible to locate Matomo plugins in different directories and it should be no longer assumed a plugin is located in the "/plugins" directory.disableQueueRequest has been added to disable queued requests which may be useful when logs are imported.LanguageManager.getAvailableLanguages has been deprecated. Use LanguagesManager.getAvailableLanguages instead.UsersManager.updateUser API, a new parameter passwordConfirmation needs to be sent along with the request containing the current password of the user issuing the API request.ScheduledReport.generateReport has been replaced by the download output type.Piwik\Piwik::doAsSuperUser has been deprecated and will be removed in Matomo 4. Use Piwik\Access::doAsSuperUser instead.queueRequest(requestUrl). This can be useful to group multiple tracking requests into one bulk request to reduce the number of tracking requests that are sent to your server making the tracking more efficient.Metrics.getEvolutionUnit which lets you set the unit for a metric used in evolution charts and row evolution.--tracker-endpoint-path parameter which allows you to use a different tracker endpoint than /piwik.php, if desired.Piwik\SettingsPiwik::isPiwikInstalled() has been deprecated and renamed to isMatomoInstalled(). It is still supported to use the method, but the method will be removed in Piwik 4.0.0Access.modifyUserAccess which lets plugins modify current user's access levels/permissions.CustomMatomoJs.manipulateJsTracker which lets plugins modify the JavaScript tracker.[tests] enable_logging INI option has been added, which you can set to 1 to enable logging for all tests. The tests:run and tests:run-ui commands now both have an --enable-logging option to enable logging for a specific run.currencies[] configuration key.eventValue lets you select all users who tracked a custom event with a given value or range of values.archiving_profile = 0, if set to 1, core:archive profiling information will be recorded in a log file. the log file is determined by the archive_profiling_log option.archive_profiling_log =, if set to an absolute path, core:archive profiling information will be logged to specified file.enable_internet_features=0 will now fully disable Internet access by preventing all outgoing connections. Note: changing this setting is not recommended for security, because you will lose the easy auto-update and email notifications.login_whitelist_ip[] now supports hostnames so you can whitelist your IP addresses and/or Hostnames and keep your Matomo secure.--concurrent-archivers to define the number of maximum archivers to run in parallel on this server. Useful to prevent archiving processes piling up and ultimately failing.API.addGlossaryItems which lets you add items to the glossary.Tracker.detectReferrerSocialNetwork which lets you add custom social network detectionsReport.unsubscribe which is triggered whenever someone unsubscribe from a reportUsersManager.getAvailableRoles to fetch a list of all available roles that can be granted to a user.UsersManager.getAvailableCapabilities to fetch a list of all available capabilities that can be granted to a user.UsersManager.addCapabilities to grant one or multiple capabilities to a user.UsersManager.removeCapabilities to remove one or multiple capabilities from a user.UsersManager.setUserAccess now accepts an array to pass a role and multiple capabilities at once.requiresInternetConnection to define if they should be automatically unloaded if no internet connection is available (enable_internet_features = 0)removeEcommerceItem and clearEcommerceCart to allow better control over what is in the e-commerce cart.&consent=1 in the Tracking API URL When consent has been given by a user.assertResponseCode() and assertHttpResponseText() in Piwik\Tests\Framework\TestCase\SystemTestCase have been deprecated and will be removed in Matomo 4.0. Please use Piwik\Http instead.PHPUnit\Framework\Constraint\HttpResponseText and PHPUnit\Framework\Constraint\ResponseCode have been deprecated and will be removed in Matomo 4.0. Please use Piwik\Http instead.--piwik-domain has been deprecated and will be removed in Matomo 4.0. Use --matomo-domain insteadPiwik\API\Request::isRootRequestApiRequest() to detect if the root request is an API request./ and will no longer include the default_action_name. e.g. path/to/index will now be /path/to/. This might affect configured custom alerts, as this plugin uses the flattened url reports for comparison.requireConsent, rememberConsentGiven, setConsentGiven, forgetConsentGiven.PrivacyManager.deleteLogsOlderThan, PrivacyManager.exportDataSubjects and PrivacyManager.deleteDataSubjects to enable plugins to be GDPR compliant.AssetManager.addStylesheets to add additional less styles which are not located in a file.Archiving.getIdSitesToMarkArchivesAsInvalidated that lets plugins customize the behaviour of report invalidations.$view->config->disable_all_rows_filter_limit.piwik font is deprecated and will be removed in Matomo 4.0. Please use new matomo font instead
Sending synchronous requests using ajaxHelper is now deprecated. All requests will be send async as of Matomo 4.0
resetUserId has been added to allow clearing user and visitor id.Actions.addActionTypes has been added, to allow plugins to add their custom action types.copyDashboardToUser, createNewDashboardForUser, removeDashboard and resetDashboardLayout
getDashboards API method has been extended by additional parameters to fetch dashboards for specific userAPI.Request.intercept has been added which allows plugins to intercept API requests to perform custom logic, overriding the original API method.Request.shouldDisablePostProcessing has been added which allows plugins to disable DataTable post processing for individual API requests.SitesManager.shouldPerformEmptySiteCheck has been added to allow plugins to disable the empty site check for individual sites.getCrossDomainLinkingUrlParameter has been added so you can add cross domain tracking capability to dynamically created links. Learn here how to append the result to said links' URLs, see the section "Advanced: Handling Dynamically Generated Links"Piwik is now Matomo. Read more about this change in the official announcement.
API.getMatomoVersion was introduced. The previous HTTP API API.getPiwikVersion will still work but will now be hidden from the API reference page.historyService along with broadcast.init, broadcast.propagateAjax, broadcast.pageLoad have been deprecated and will be removed in Piwik 4.@theme-color-header-textWidgetize.shouldEmbedIframeEmpty added so plugins can optionally define the output of the widgetized HTML themselvesLive.addProfileSummaries and Live.filterProfileSummariespiwikHelper.registerShortcut allows plugins to bind keyboard shortcuts. A summary for available shortcuts will be shown by pressing ?visitStartServerMinute for Server time - minute (Start of visit)visitEndServerMinute for Server time - minute (End of visit)Live.addVisitorDetails and Live.filterVisitorDetails$view->config->show_export.$view->config->show_header_message.Metric.addMetrics Triggered to add new metrics that cannot be picked up automatically by the platform.Metric.addComputedMetrics Triggered to add computed metrics that are not generated automaticallyMetric.filterMetrics Triggered to filter metricsPiwik\Columns\MetricsList Holds a list of all available metricsPiwik\Columns\ComputedMetricFactory Can be used to create computed metricsPiwik\Columns\DimensionMetricFactory Can be used to create metrics directly within a dimensionshow_update_notification_to_superusers_only makes it possible to hide update notifications for all users except of superusersLive.getAllVisitorDetails has been deprecated and will be removed in Piwik 4. Use a VisitorDetails class instead (see Live plugin).setSecureCookie that sets the cookie's secure parameterScheduledTasks.shouldExecuteTask, ScheduledTasks.execute, ScheduledTasks.execute.end have been added to customize the behaviour of scheduled tasks.CustomPiwikJs.shouldAddTrackerFile has been added to let plugins customize which tracker files should be included in piwik.js JavaScript trackerLogin.authenticate.successful has been added, which is triggered when a user successful signs inPiwik\Plugins\CustomPiwikJs\TrackerUpdater has been added to update the piwik.js JavaScript trackerplugin:activate and plugin:deactivate can now activate and deactivate multiple plugins at onceDb.getActionReferenceColumnsByTable has been added in case a plugin defines a custom log table which references data to the log_action tableSystem.addSystemSummaryItems and System.filterSystemSummaryItems have been added so plugins can add items and filter items of the system summary widgetgetPiwikUrl has been added to retrieve the URL of where the Piwik instance is locatedgetCurrentUrl has been added to retrieve the current URL of the website.getNumTrackedPageViews has been added to retrieve the number of tracked page views within the currently loaded page or web application.setSessionCookie, getCookie, hasCookies, getCookieDomain, getCookiePath, and getSessionCookieTimeout have been added for better cookie support in plugins.email and url form fields can now be used in settings.enable_plugin_upload lets you enable uploading and installing a Piwik plugin ZIP file by a Super User. This used to be enabled by default, but it is now disabled by default now for security reasons.Report::$supportsFlatten lets you define if a report supports flattening (defaults to true). If set to false it will also set ViewDataTable\Config::$show_flatten_table to falseController.triggerAdminNotifications has been added to let plugins know when they are supposed to trigger notifications in the admin.enableCrossDomainLinking, disableCrossDomainLinking, isCrossDomainLinkingEnabledgetLinkTrackingTimer to get the value of the configured link tracking timedeleteCustomVariables to delete all custom variables within a certain scopeenableLinkTracking can now be called several times to make Piwik aware of newly added links when your DOM changesPiwik\Plugin\Report::getMetricNamesToProcessReportTotals() that lets you define which metrics should show percentages in the table report visualization on hover. If defined, these percentages will be automatically calculated.Tracker.newConversionInformation now posts a new fourth parameter $actionUserCountry.getCountryCodeMapping to get a list of used country codes to country namesgetCredentialFields(). This allows to have SMS providers that require more than only an API key.setSMSAPICredential() now takes the second parameter as an array filled with credentials (instead of a string containing an API key)MultiSites.filterRowsForTotalsCalculation to filter which sites will be included in the All Websites Dashboard totals calculation.Piwik\Plugin\Archiver::shouldRunEvenWhenNoVisits() has been added. By overwriting this method and returning true, a plugin archiver can force the archiving to run even when there was no visit for the website/date/period/segment combination (by default, archivers are skipped when there is no visit).Read more about migrating a plugin from Piwik 2.X to Piwik 3 in our Migration guide.
_paq.push, it is now required to configure the tracker (eg calling setSiteId and setTrackerUrl) before the piwik.js JavaScript tracker is loaded to ensure the tracker works correctly.
If the tracker is not initialised correctly, the browser console will display the error "_paq.push() was used but Piwik tracker was not initialized before the piwik.js file was loaded. [...]"token_auth properties when requesting a userPiwik\Menu\MenuReporting and Piwik\Menu\MenuMain have been removedPiwik\Plugin\Widgets has been removed and replaced by Piwik\Widget\Widget. For each widget one class is needed from now on. You can generate a widget via ./console generate:widget.Piwik\WidgetList class has been moved to Piwik\Widget\WidgetsList.Piwik\Plugins\API\API::getLastDate() has been removed.Piwik\Archive::getDataTableFromArchive() has been removed, use Piwik\Archive::createDataTableFromArchive instead.Piwik\Plugin\Menu::configureReportingMenu has been removed. To add something to the reporting menu you need to create widgetsReport::configureWidget(), Report::getWidgetTitle() and Report::configureReportingMenu() have been removed, use the new method Report::configureWidgets() instead.Report::getCategory() has been moved to Report::getCategoryId() and does no longer return the translated category but the translation key of the category.Report::$category has been renamed to Report::$categoryIdReport::factory(), Report::getAllReportClasses(), Report::getAllReports have been moved to the Piwik\Plugin\Reports class.Report::$widgetTitle, Report::$widgetParams and Report::$menuTitle were removed, use the method Report::configureWidgets() to create widgets insteadDashboard.getDefaultDashboard and Dashboard.getUserDashboards we do no longer remove not existing widgets as it is up to the client which widgets actually existPiwik\Plugin\Controller::getEvolutionHtml has been removed without a replacement as it should be no longer needed. The evolution is generated by ViewDataTables directlycore:plugin console command has been removed in favor of the new plugin:list, plugin:activate and plugin:deactivate commands as announced in Piwik 2.11Piwik\Plugins\Login\Controller were changed to protectedconfigureUserMenu(MenuUser $menu) to configureAdminMenu(MenuAdmin $menu) in your Menu.php.Piwik\Menu\MenuAbstract::add() has been removed, use Piwik\Menu\MenuAbstract::addItem() insteadPiwik\Menu\MenuAdmin::addSettingsItem() was removed, use Piwik\Menu\MenuAdmin::addSystemItem() instead.Piwik\Menu\MenuAdmin::addMeasurablesItem() was added.Piwik\Plugin\Settings has been split to Piwik\Settings\Plugin\SystemSettings and Piwik\Settings\Plugin\UserSettings.$this->makeSetting() see Piwik\Plugins\ExampleSettingsPlugin\SystemSettings for an example.<result date="From 2010-02-01 to 2010-02-07"> which is now <result date="2010-02-01,2010-02-07">.Tracker.existingVisitInformation Use dimensions instead of using Tracker events.Tracker.newVisitorInformationTracker.recordActionTracker.recordEcommerceGoalTracker.recordStandardGoalsAPI.getSegmentDimensionMetadata Define segments in Dimension insteadMenu.Admin.addItems Create a Menu instead of using Menu eventsMenu.Reporting.addItemsMenu.Top.addItemsViewDataTable.addViewDataTable Create a Visualization insteadViewDataTable.getDefaultType Specify the default type in a Report insteadLogin.authenticate Create a custom SessionInitializer instead of using Login eventsLogin.initSession.endLogin.authenticate.successfulAPI.Request.dispatch, API.Request.dispatch.end, API.$plugin.$apiAction, or API.$plugin.$apiAction.end the $finalParameters parameter is indexed in Piwik 2 (eg array(1, 6)), and named in Piwik 3 (eg array('idSite' => 1, 'idGoal' => 6))UserSettings plugin won't work any longer. Please update the module and action parameter in the widget url according to the following list| old module | old action | new module | new action |
|---|---|---|---|
| UserSettings | getPlugin | DevicePlugins | getPlugin |
| UserSettings | index | DevicesDetection | software |
| UserSettings | getBrowser | DevicesDetection | getBrowsers |
| UserSettings | getBrowserVersions | DevicesDetection | getBrowserVersions |
| UserSettings | getMobileVsDesktop | DevicesDetection | getType |
| UserSettings | getOS | DevicesDetection | getOsVersions |
| UserSettings | getOSFamily | DevicesDetection | getOsFamilies |
| UserSettings | getBrowserType | DevicesDetection | getBrowserEngines |
| UserSettings | getResolution | Resolution | getResolution |
| UserSettings | getConfiguration | Resolution | getConfiguration |
| UserSettings | getLanguage | UserLanguage | getLanguage |
| UserSettings | getLanguageCode | UserLanguage | getLanguageCode |
Read more about migrating a plugin from Piwik 2.X to Piwik 3 on our Migration guide.
Piwik\Updates::getMigrationQueries() has been deprecated and renamed to getMigrations(). It is still supported to use the method, but the method will be removed in Piwik 4.0.0Piwik\Updater::executeMigrationQueries() has been deprecated and renamed to executeMigrations. It is still supported to use the method, but the method will be removed in Piwik 4.0.0.Report::configureWidgets() method via the new classes Piwik\Widget\ReportWidgetFactory and Piwik\Widget\ReportWidgetConfigReport::$subCategory that lets you add a report to the reporting UI. If a page having that name does not exist yet, it will be created automatically. The newly added method Report::getSubCategory() lets you get this value.Piwik\Widget\Widget, Piwik\Widget\WidgetConfig and Piwik\Widget\WidgetContainerConfig lets you create a new widget.Piwik\Category\Subcategory let you change the name and order of menu itemsAPI.getWidgetMetadata to get a list of available widgetsAPI.getReportPagesMetadata to get a list of all available pages that exist including the widgets they includeSitesManager.getSiteSettings to get a list of all available settings for a specific siteajaxHelper.withTokenInUrl() to easily send a token along a XHR. Within the Controller the existence of this token can be checked via $this->checkTokenInUrl(); to prevent CSRF attacks.Piwik\Updater\Migration\Factory lets you easily create migrations that can be executed during an update. For example database or plugin related migrations. To generate a new update with migrations execute ./console generate:update.Piwik\Updater::executeMigration lets you execute a single migration.Piwik\Segment::willBeArchived lets you detect whether a segment will be archived or not.ViewDataTable.filterViewDataTable lets you filter available visualizationsDimension.addDimension lets you add custom dimensionsDimension.filterDimension lets you filter any dimensionsReport.addReports lets you add dynamically created reportsReport.filterReports lets you filter any reportUpdater.componentUpdated triggered after core or a plugin has been updatedPluginManager.pluginInstalled triggered after a plugin was installedPluginManager.pluginUninstalled triggered after a plugin was uninstalledUpdater.componentInstalled triggered after a component was installedUpdater.componentUninstalled triggered after a component was uninstalledpv_id which accepts a six character unique ID that identifies which actions were performed on a specific page view. Read more about it in the HTTP Tracking API;Segment.addSegments that lets you add segments.disableHeartBeatTimer() to disable the heartbeat timer if it was previously enabled.SitesManager.getJavascriptTag has a new option getJavascriptTag to enable the tracking of users that have JavaScript disabledtracking_requests_require_authentication_when_custom_timestamp_newer_than to change how far back Piwik will track your requests without authentication. By default, value is set to 86400 (one day). The configured value is in seconds.trackRequest that allows you to send any tracking parameters to Piwik. For example _paq.push(['trackRequest', 'te=foo&bar=baz'])expected-ui-screenshots to expected-screenshots. The UI-Test-Runner is now able to handle both names._paq.push(['addTracker', piwikUrl, piwikSiteId]). All tracking requests will be then sent to all added Piwik trackers. Learn more.addTracker) via the method Piwik.getAsyncTracker(optionalPiwikUrl, optionalPiwikSiteId). This allows you to get the tracker instance and to send different tracking requests to this Piwik instance and to configure it differently than other tracker instances.Goals.getGoal($idSite, $idGoal) to fetch a single goal.piwik.js, if you call the method setDomains note that that the behavior has slightly changed. The current page domain (hostname) will now be added automatically if none of the given host alias passed as a parameter to setDomains contain a path and if no host alias is already given for the current host alias.
Say you are on "example.org" and set hostAlias = ['example.com', 'example.org/test'] then the current "example.org" domain will not be added as there is already a more restrictive hostAlias 'example.org/test' given.
We also do not add the current page domain (hostname) automatically if there was any other host specifying any path such as ['example.com', 'example2.com/test'].
In this case we also do not add the current page domain "example.org" automatically as the "path" feature is used. As soon as someone uses the path feature, for Piwik JS Tracker to work correctly in all cases, one needs to specify all hosts manually. Learn more.piwik.js: after an e-commerce order is tracked using trackEcommerceOrder, the items in the cart will now be removed from the JavaScript object. Calling trackEcommerceCartUpdate will not remove the items in the cart.setIsWritableByCurrentUser for SystemSetting to change the writable permission for certain system settings via DI.setDomains function now supports page wildcards matching eg. example.com/index* which can be useful when tracking a group of pages within a domain in a separate website in Piwikurl_query_parameter_to_exclude_from_url INI setting in your config.ini.php file. By default, the following query string parameters will be removed: gclid, fb_xd_fragment, fb_comment_id, phpsessid, jsessionid, sessionid, aspsessionid, doing_wp_cron, sid.SettingsServer::isApache()=, - or +, Piwik will now prefix the value with ' to ensure that it is displayed correctly in Excel or OpenOffice/LibreOffice.sid if it is found.setDomains will not anymore attempt to set a cookie path. Learn more about configuring the tracker correctly when tracking one or several domains and/or paths.[General]enable_marketplace=0/1 was removed, instead the new plugin Marketplace can be disabled/enabled. The updater should automatically migrate an existing setting.actionType lets you segment all actions of a given type, eg. actionType==events or actionType==downloads. Action types values are: pageviews, contents, sitesearches, events, outlinks, downloadsactionUrl lets you segment any action that matches a given URL, whether they are Pageviews, Site searches, Contents, Downloads or Events.deviceBrand lets you restrict your users to those using a particular device brand such as Apple, Samsung, LG, Google, Nokia, Sony, Lenovo, Alcatel, etc. View the complete list of device brands.=^ "Starts with" and =$ "Ends with" complement the existing segment operators: Contains, Does not contain, Equals, Not equals, Greater than or equal to, Less than or equal to.PiwikTracker.setDomains() can now handle paths. This means when setting eg _paq.push(['setDomains, '*.matomo.org/website1']) all link that goes to the same domain matomo.org but to any other path than website1/* will be treated as outlink.php-cli-options to the core:archive command. The given cli options will be forwarded to the actual PHP command. This allows to for example specify a different memory limit for the archiving process like this: ./console core:archive --php-cli-options="-d memory_limit=8G"@theme-color-menu-contrast-textSelected that lets you specify the color of a selected menu item.Config file which lets Super User view all config values from global.ini.php in the UI, and whether they were overridden in your config/config.ini.phpconfig:set lets you set INI config options from the command line. This command can be used for convenience or for automation.UsersManager.* API calls: when an API request specifies a token_auth of a user with admin permission, the returned dataset will not include all usernames as previously, API will now only return usernames for users with view or admin permission to website(s) viewable by this token_auth.generate:plugin command, plugin name must now contain only letters and numbers.SQLite. The existing MySQL configuration for tests is used now. In order to run the tests make sure Piwik is installed and [database_tests] is configured in config/config.ini.php.configOverride setting should be no longer overwritten. Instead new values should be added to the existing configOverride array in PHP or JavaScript. For example instead of testEnvironment.configOverride = {group: {name: 1}} use testEnvironment.overrideConfig('group', 'name', '1').SMSProvider directory of your plugin. The class has to extend Piwik\Plugins\MobileMessaging\SMSProvider and implement the required methods.$segment->setUnionOfSegments(array('outlinkUrl', 'downloadUrl')) instead of defining a SQL column.DB::tableExists was un-used and has been removed.diagnostics:analyze-archive-table that analyzes archive tablesdatabase:optimize-archive-tables to optimize archive tables and possibly save disk space (even if on InnoDB)core:invalidate-report-data to invalidate archive data (w/ period cascading) (FAQ)piwik.js got a new method logAllContentBlocksOnPage to log all found content blocks within a page to the console. This is useful to debug / test content tracking. It can be triggered via _paq.push(['logAllContentBlocksOnPage'])Piwik\Plugins\Login\Controller is now considered a public API.Piwik\Menu\MenuAbstract::registerMenuIcon() can be used to define an icon for a menu category to replace the default arrow icon.CronArchive.getIdSitesNotUsingTracker that allows you to set a list of idSites that do not use the Tracker API to make sure we archive these sites if needed.CronArchive.init.start which is triggered when the CLI archiver starts and CronArchive.end when the archiver ended.Dimension::getId() has been set as final. It is not allowed to overwrite this method.Sites.getPatternMatchSites only returned a very limited number of websites by default. We now return all websites by default unless a limit is specified specifically.enable_measure_piwik_usage_in_idsite which is used to track the Piwik usage with Piwik was removed and replaced by a new plugin AnonymousPiwikUsageMeasurementSitesManager.getSitesIdWithVisitsAPI.getLastDateTracker.existingVisitInformationTracker.getVisitFieldsToPersistTracker.newConversionInformationTracker.newVisitorInformationTracker.recordActionTracker.recordEcommerceGoalTracker.recordStandardGoals\Piwik\Plugin::getListHooksRegistered() has been deprecated and will be removed in Piwik 4.0. Use \Piwik\Plugin::registerEvents() instead.�piwik.js we replaced JSON2 with JSON3 to implement CSP (Content Security Policy) as JSON3 does not use eval(). JSON3 will be used if a browser does not provide a native JSON API. We are using JSON3 in a way that it will not conflict if your website is using JSON3 as well.branch of the console command development:sync-system-test-processed was removed as it is no longer needed.1,000,000 instead of 1000000)UTF-8 charset explicitly to force UTF-8 data handlingUserSettings API has been removed. The API was deprecated in earlier versions. Use DevicesDetection, Resolution and DevicePlugins API instead.enabled parameter of the enableLinkTracking() method is set to true. To use this new feature use tracker.enableLinkTracking(true) or _paq.push(['enableLinkTracking', true]);. This is not industry standard and is vulnerable to false positives since not every user will select "Open in a new tab" when the context menu is shown. Most users will do though and it will lead to more accurate results in most cases.tracker.enableHeartBeatTimer(); or _paq.push(['enableHeartBeatTimer']);. By default, a ping request will be sent every 15 seconds. You can specify a custom ping delay (in seconds) by passing an argument, eg, tracker.enableHeartBeatTimer(10); or _paq.push(['enableHeartBeatTimer', 10]);.languageCode that lets you segment visitors that are using a particular language. Example values: de, fr, en-gb, zh-cn, etc.userId now supports any segment operator (previously only operator Contains =@ was supported for this segment).core:archive now has two new parameter: --force-idsegments and --skip-idsegments that let you force (or skip) processing archives for one or several custom segments.scheduled-tasks:run now has an argument task that lets you force run a particular scheduled task.libs/pChart2.1.3 to libs/pChartLive.getLastVisitsDetails does no longer support the API parameter filter_sort_column to prevent possible memory issues when filter_offset is large.Site.setSite was removed as it causes performance problems.piwik.php does now return a HTTP 400 (Bad request) if requested without any tracking parameters (GET/POST). If you still want to use piwik.php for checks please use piwik.php?rec=0.Piwik\Archive::getBlob() has been deprecated and will be removed from June 1st 2015. Use one of the methods getDataTable*() methods instead.countVisitorsToFetch of the API method Live.getLastVisitsDetails has been deprecated as filter_offset and filter_limit work correctly now.diagnostic:run command to run the system check from the command line.--xhprof that can be used with any command to profile that command via XHProf.deviceTypeIcon, deviceBrand and deviceModelfilter_limit and filter_offset if an API returns an indexed array. This was not working in all cases and is fixed now.filter_pattern and filter_offset[] can now be used if an API returns an indexed array.referrer_urls_spam INI option (in global.ini.php) to a separate package (see https://github.com/matomo-org/referrer-spam-list).Period::factory() has been removed. Use Period\Factory instead.Config::getConfigSuperUserForBackwardCompatibility() has been removed.MenuAdmin::addEntry() and MenuAdmin::removeEntry() have been removed. Use Piwik\Plugin\Menu instead.MenuTop::addEntry() and MenuTop::removeEntry() have been removed. Use Piwik\Plugin\Menu instead.SettingsPiwik::rewriteTmpPathWithInstanceId() has been removed.Piwik\IP class have been removed, use Piwik\Network\IP instead:
sanitizeIp()sanitizeIpRange()P2N()N2P()prettyPrint()isIPv4()long2ip()isIPv6()isMappedIPv4()getIPv4FromMappedIPv6()getIpsForRange()isIpInRange()getHostByAddr()API classes should no longer have a protected constructor. Classes with a protected constructor will generate a notice in the logs and should expose a public constructor instead.getSql() and update() methods anymore. It is still supported to use those, but developers should instead override the Updates::getMigrationQueries() and Updates::doUpdate() instance methods.API classes can now use dependency injection in their constructor to inject other instances.core:purge-old-archive-data that can be used to manually purge temporary, error-ed and invalidated archives from one or more archive tables.usercountry:attribute that can be used to re-attribute geolocated location data to existing visits and conversions. If you have visits that were tracked before setting up GeoIP, you can use this command to add location data to them.User.getLanguage has been removed.TaskScheduler.getScheduledTasksWindows has been removed. Like other operating systems all versions will now only be reported as Windows with versions like XP, 7, 8, etc.operatingSystemName, operatingSystemIcon, operatingSystemCode and operatingSystemVersionPiwik\Intl component:
Piwik\Common::getContinentsList(): use RegionDataProvider::getContinentList() insteadPiwik\Common::getCountriesList(): use RegionDataProvider::getCountryList() insteadPiwik\Common::getLanguagesList(): use LanguageDataProvider::getLanguageList() insteadPiwik\Common::getLanguageToCountryList(): use LanguageDataProvider::getLanguageToCountryList() insteadPiwik\Metrics\Formatter::getCurrencyList(): use CurrencyDataProvider::getCurrencyList() insteadPiwik\Translate class has been deprecated in favor of Piwik\Translation\Translator.core:plugin console has been deprecated in favor of the new plugin:list, plugin:activate and plugin:deactivate commandsPiwik\TaskScheduler: use Piwik\Scheduler\Scheduler insteadPiwik\ScheduledTask: use Piwik\Scheduler\Task insteadUserSettings.getLanguage is deprecated and will be removed from May 1st 2015. Use UserLanguage.getLanguage insteadUserSettings.getLanguageCode is deprecated and will be removed from May 1st 2015. Use UserLanguage.getLanguageCode insteadPiwik\Registry class has been deprecated in favor of using the container:
Registry::get('auth') should be replaced with StaticContainer::get('Piwik\Auth')Registry::set('auth', $auth) should be replaced with StaticContainer::getContainer()->set('Piwik\Auth', $auth)generate:testuiTest. This allows you do hide content when screenshots are captured.tests/PHPUnit/UI to tests/UI. We also moved the UI specs directly into the Piwik repository meaning the piwik-ui-tests repository contains only the expected screenshots from now on.development:sync-system-test-processed for core developers that allows you to copy processed test results from travis to your local dev environment.screenType and screenTypeIcon as those reports have been completely removedPiwik\SettingsPiwik::rewriteTmpPathWithHostname() has been removed.Log.formatFileMessageLog.formatDatabaseMessageLog.formatScreenMessageLog.getAvailableWriters has been removed: to add custom log backends, you now need to configure Monolog handlerslog_only_when_cli and log_only_when_debug_parameter have been removedsymfony/var-dumper library allowing you to better print any arbitrary PHP variable via dump($var1, $var2, ...).misc/proxy-hide-piwik-url/) has been moved to a separate repository: https://github.com/matomo-org/tracker-proxy.UserSettings.getBrowserVersion is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getBrowserVersions insteadUserSettings.getBrowser is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getBrowsers insteadUserSettings.getOSFamily is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getOsFamilies insteadUserSettings.getOS is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getOsVersions insteadUserSettings.getMobileVsDesktop is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getType insteadUserSettings.getBrowserType is deprecated and will be removed from May 1st 2015. Use DevicesDetection.getBrowserEngines insteadUserSettings.getResolution is deprecated and will be removed from May 1st 2015. Use Resolution.getResolution insteadUserSettings.getConfiguration is deprecated and will be removed from May 1st 2015. Use Resolution.getConfiguration insteadUserSettings.getPlugin is deprecated and will be removed from May 1st 2015. Use DevicePlugins.getPlugin insteadUserSettings.getWideScreen has been removed. Use UserSettings.getScreenType instead.Piwik\SettingsPiwik::rewriteTmpPathWithInstanceId() has been deprecated. Instead of hardcoding the tmp/ path everywhere in the codebase and then calling rewriteTmpPathWithInstanceId(), developers should get the path.tmp configuration value from the DI container (e.g. StaticContainer::getContainer()->get('path.tmp')).Piwik\Log::setLogLevel() has been deprecatedPiwik\Log::getLogLevel() has been deprecatedidsite is usedsend_image=0 in the HTTP Tracking API to receive a HTTP 204 response code instead of a GIF image. This improves performance and can fix errors if images are not allowed to be obtained directly (eg Chrome Apps).core:plugin list lists all plugins currently activated in Piwik../console development:enable.php console core:update does no longer have a parameter --dry-run. A dry run is now executed by default followed by a question whether one actually wants to execute the updates. To skip this confirmation step one can use the --yes option.Piwik\IP have been deprecated in favor of the new piwik/network component.tests/PHPUnit/phpunit.xml is no longer needed in order to run tests and we suggest to delete it. The test configuration is now done automatically if possible. In case the tests do no longer work check out the [tests] section in config/global.ini.phpPiwik\Unzip\* classes have been extracted out of the Piwik repository into a separate component named Decompress.
Piwik\Unzip has not moved, it is kept for backward compatibility. If you have been using that class, you don't need to change anything.Piwik\Unzip\* classes (Tar, PclZip, Gzip, ZipArchive) have moved to the Piwik\Decompress\* namespace (inside the new repository).Piwik\Unzip\UncompressInterface has been moved and renamed to Piwik\Decompress\DecompressInterface (inside the new repository).Piwik::setUserHasSuperUserAccess method is deprecated, instead use Access::doAsSuperUser. This method will ensure that super user access is properly rescinded after the callback finishes.\IntegrationTestCase is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\TestCase\SystemTestCase instead.\DatabaseTestCase is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\TestCase\IntegrationTestCase instead.\BenchmarkTestCase is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\TestCase\BenchmarkTestCase instead.\ConsoleCommandTestCase is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\TestCase\ConsoleCommandTestCase instead.\FakeAccess is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\Mock\FakeAccess instead.\Piwik\Tests\Fixture is deprecated and will be removed from February 6th 2015. Use \Piwik\Tests\Framework\Fixture instead.\Piwik\Tests\OverrideLogin is deprecated and will be removed from February 6ths 2015. Use \Piwik\Framework\Framework\OverrideLogin instead.generate:angular-directive lets you easily generate a template for a new angular directive for any plugin.nb_users which measures the number of unique users when a User ID is set.Piwik\Menu\MenuAbstract::add() method is deprecated in favor of addItem(). Read more about this here: #6140. We do not plan to remove the deprecated method before Piwik 3.0.core:clear-caches Lets you easily delete all caches. This command can be useful for instance after updating Piwik files manually.'json' API format is considered deprecated. We ask all new code to use the 'json2' format. Eventually when Piwik 3.0 is released the 'json' format will be replaced with 'json2'. Differences in the json2 format include:
array('name' => 'value', 'name2' => 'value2') will now appear correctly as {"name":"value","name2":"value2"} in JSON API output instead of [{"name":"value","name2":"value2"}]. API methods like SitesManager.getSiteFromId & UsersManager.getUser are affected.filter_limit and filter_offset. This was before only possible if an API returned a DataTable.getLastVisitDetails or getVisitorProfile. If all core plugins are enabled as by default there will be no change at all except the order of the properties within one visitor.core:run-scheduled-tasks lets you run all scheduled tasks due to run at this time. Useful for instance when testing tasks.core/Loader.php will no longer exist. In case you are using Piwik from Git make sure to run php composer.phar self-update && php composer.phar install to make your Piwik work again. Also make sure to no longer include core/Loader.php in case it is used in any custom script.Tracker.* or Request.initAuthenticationObject event or it has to define dimensions in order to be detected as a tracker plugin.getCustomVariable function to access custom variables values that were set on previous page views, you now must also call storeCustomVariablesInCookie before the first call to trackPageView. Read more about Javascript Tracking here.& to &. If you still want this behavior - for instance to prevent XSS - you can define a filter by setting the transform property like this:
$setting->transform = function ($value) { return Common::sanitizeInputValue($value); }disable_merged_assets moved from Debug section to Development. The updater will automatically change the section for you.API.getRowEvolution will throw an exception if a report is requested that does not have a dimension, for instance VisitsSummary.get. This is a fix as an invalid format was returned before see #5951MultiSites.getAll returns from now on always an array of websites. In the past it returned a single object and it didn't contain all properties in case only one website was found which was a bug see #5987The following events are considered as deprecated and the new structure should be used in the future. We have not scheduled when those events will be removed but probably in Piwik 3.0 which is not scheduled yet and won't be soon. New features will be added only to the new classes.
API.getReportMetadata, API.getSegmentDimensionMetadata, Goals.getReportsWithGoalMetrics, ViewDataTable.configure, ViewDataTable.getDefaultType: use Report class instead to define new reports. There is an updated guide as well Part1WidgetsList.addWidgets: use Widgets class instead to define new widgetsMenu.Admin.addItems, Menu.Reporting.addItems, Menu.Top.addItems: use Menu class insteadTaskScheduler.getScheduledTasks: use Tasks class instead to define new tasksTracker.recordEcommerceGoal, Tracker.recordStandardGoals, Tracker.newConversionInformation: use Conversion Dimension class insteadTracker.existingVisitInformation, Tracker.newVisitorInformation, Tracker.getVisitFieldsToPersist: use Visit Dimension class insteadViewDataTable.addViewDataTable: This event is no longer needed. Visualizations are automatically discovered if they are placed within a Visualizations directory inside the plugin.As a plugin developer you might want to reuse existing translation keys. You can now find all available translations and translation keys by opening the page "Settings => Development:Translation search" in your Piwik installation. Read more about internationalization here.
It is now possible to use the filter_sort_column parameter when requesting Live.getLastVisitDetails. For instance &filter_sort_column=visitCount.
We are using @since annotations in case we are introducing new API's to make it easy to see in which Piwik version a new method was added. This information is now displayed in the Classes API-Reference.
Reportsgenerate:theme lets you easily generate a new theme and customize colors, see the Theming guidegenerate:update lets you generate an update filegenerate:report lets you generate a reportgenerate:dimension lets you enhance the tracking by adding new dimensionsgenerate:menu lets you generate a menu class to add or modify menu itemsgenerate:widgets lets you generate a widgets class to add or modify widgetsgenerate:tasks lets you generate a tasks class to add or modify tasksdevelopment:enable lets you enable the development mode which will will disable some caching to make code changes directly visible and it will assist developers by performing additional checks to prevent for instance typos. Should not be used in production.development:disable lets you disable the development modeFind the general Matomo Changelogs for each release at matomo.org/changelog