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.
The API method Overlay.getExcludedQueryParameters
has been deprecated and will be removed in Matomo 6. Use the new method SitesManager.getExcludedQueryParameters
instead.
- AngularJS has been completely removed from the code base, existing AngularJS code will no longer work. It is recommended to convert that code to Vue.
- jQuery has been updated to 3.6.3. Please check your plugins javascript code if it needs to be adjusted. More details can be found in jQuery update guides: https://jquery.com/upgrade-guide/3.0/ and https://jquery.com/upgrade-guide/3.5/
- The
Common::fixLbrace()
function has been removed. It was only necessary for AngularJS and no longer needs to be used. - The deprecated
JSON2
API format has now been removed. We recommend switching to theJSON
renderer, which behaves the same. - The javascript event
piwikPageChange
, which is triggered when a reporting page is loaded, has been renamed tomatomoPageChange
. Ensure to update your implementation if you rely on it. - The deprecated javascript functions
broadcast.init
,broadcast.propagateAjax
andbroadcast.pageLoad
have been removed. - Plugin names are now limited to 60 characters. If you used to have a plugin with a longer name, you might need to rename it.
- The
instance_id
configuration does no longer support characters other thana-z
,0-9
and the special characters.-_
. If the configured value contains other characters, they will be simply removed. - When an invalid token is provided in an API request, a 401 response code is now returned instead of 200 response code.
- By default, the
file:https://
protocol is no longer tracked. To enable tracking of thefile:https://
protocol use the new JavaScript tracker methodenableFileTracking
(learn more). - We have migrated our automated tests from Travis CI to GitHub actions. If your plugin used Travis CI for running tests ensure to migrate that to a GitHub action as support for running tests on Travis has been dropped.
- By default, the last ip address in the proxy list will now be used rather than the first ip address. To force the first ip address to be used set the config option
proxy_ip_read_last_in_list = 0
. - The deprecated method
Piwik\Log::setLogLevel()
has been removed - The deprecated method
Piwik\Log::getLogLevel()
has been removed - A parameter
$login
has been added to the methodssetCompleted()
,isCompleted()
,skipChallenge()
andisSkipped()
in thePiwik\Plugins\Tour\Engagement\Challenge
class - In order to encapsulate Matomo's dependencies from direct usage in plugins we introduce some proxy classes and patterns that need to be used instead. For plugin development avoid using any external Matomo dependency directly.
- Use
Piwik\Log\Logger
instead ofMonolog\Logger
- Use
Piwik\Log\LoggerInterface
instead ofPsr\Log\LoggerInterface
- Use
Piwik\Log\NullLogger
instead ofPsr\Log\NullLogger
- Use
Piwik\DI
instead ofDI
DI
namespaced functions need to be replaced with staticPiwik\DI
methods. E.g.DI\add()
will becomePiwik\DI::add()
- If you need to catch dependency related exceptions use
Piwik\Exception\DI\DependencyException
orPiwik\Exception\DI\NotFoundException
- We are now using our own Container class. So when defining dependencies use
\Piwik\Container\Container
where you used to use\Psr\Container\ContainerInterface
orDI\Container
as typehints
- To encapsulate plugin commands from directly using any symfony console dependency our class
Piwik\Plugins\ConsoleCommand
has been rewritten. To migrate your commands you need to apply some changes:- Methods like
run
,execute
,interact
orinitialize
can no longer be overwritten. Instead, use our custom methods prefixed withdo
:doExecute
,doInteract
ordoInitialize
doExecute()
method needs to return integers. We recommend using the class constantsSUCCESS
orFAILURE
as return values.
- Where ever you need to work with input or output use
$this->getInput()
or$this->getOutput()
instead. Don't useInputInterface
orOutputInterface
as method typehints. - When defining input options and arguments
addOption
andaddArgument
can no longer be used- For arguments use
addOptionalArgument
oraddRequiredArgument
- For options use
addNegatableOption
,addOptionalValueOption
,addNoValueOption
oraddRequiredValueOption
- For arguments use
- Directly using any console helpers is now prohibited
- When needing user input use the new methods
askForConfirmation
,askAndValidate
orask
- For progress bars use the methods
initProgressBar
,startProgressBar
,advanceProgressBar
andfinishProgressBar
- Tables can be rendered using the new method
renderTable
- When needing user input use the new methods
- For executing another command within your command use the new method
runCommand
- Methods like
- Use
- Requests sent by Matomo to plugins.matomo.org will no longer include an
HTTP_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. - Matomo does no longer include the jQuery browser plugin. If your plugin requires it, you need to include it yourself.
- The class
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 ofCommon::getRequestVar
. - All API are now able to overwrite the property
$autoSanitizeInputParams
. Setting this variable tofalse
will prevent an automatic apply ofCommon::sanitizeInputValues
on all parameter passed to the API methods. By now this property defaults totrue
, but this might change in upcoming major releases. - All API methods can now use type hinted parameters. This allows to force certain parameters to be provided in a defined type. If the API is called with a mismatching type, an error will be triggered, without calling the method at all. Only basic types are supported: string, int, float, bool, array
- The method
Common::getRequestVar
is now deprecated, but will remain API until Matomo 6. You may already start using the new classPiwik\Request
instead, but ensure to handle needed sanitizing / escaping yourself. - The brand related less variables for colors
color-black-piwik
,color-blue-piwik
,color-red-piwik
andcolor-green-piwik
are now deprecated and will be removed in Matomo 6. New variables wherepiwik
was replaced withmatomo
have been introduced. E.g.color-black-matomo
- Support for jQuery UI is now depreated and might be removed in one of the next major releases. Please consider using Materialize CSS or Vue.js instead.
- The segment subquery cache, previously enabled via the
enable_segments_subquery_cache
INI config, has been removed. Segment SQL queries that reference actions now directly join log_action. Related INI config optionssegments_subquery_cache_ttl
andsegments_subquery_cache_limit
have also been removed.
- Requests to ASPSMS and Clockwork API do no longer accept invalid SSL certificates. If you experience problems with mobile messaging please check your SSL setup.
- When posting the event
Archiving.getIdSitesToMarkArchivesAsInvalidated
started passing date, period ,segment and name parameter along with idSites parameter.
- The default maximum number of archivers processes to run concurrently has changed from unlimited to three. The
--concurrent-archivers
parameter can be used to increase this limit. A value of -1 will use an unlimited number of concurrent archivers
- By default, new authentication tokens will be restricted to be used in POST requests only. This is recommended for improved security. This option can be unselected when creating a new token. Existing tokens will continue to work with both, POST and GET requests.
- A new config setting
only_allow_secure_auth_tokens
, defaulting to0
, has been added. Enabling this option will prevent any use of tokens in GET API requests.
- The campaign attribution tracking parameters
_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 camapign parameters to the tracked URL instead.
- Three new config settings
ssl_disallow_self_signed
,ssl_verify_peer
,ssl_verify_peer_name
under [mail] to allow modifying the SSL handling in SMTP request.
- A new config setting
enable_opcache_reset
defaulting to1
. Provides a configuration switch foropcache_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.
- When removing a user through the
UsersManager.deleteUser
API using a session authentication, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request. - When adding a user through the
UsersManager.addUser
API using a session authentication, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request. - When inviting a user through the
UsersManager.inviteUser
API using a session authentication, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request.
- Added new event
Login.userRequiresPasswordConfirmation
, which can be used in login plugins to circumvent the password confirmation in UI and for certain API methods - When removing a site through the
SitesManager.deleteSite
API using a session authentication, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request.
- The privacy manager iframe opt-out UI has been replaced with a choice of either generating JavaScript opt-out code which uses the Matomo tracker, or generating self-contained JavaScript opt-out code which directly sets the consent cookies. Existing iframe opt-outs will still work, but iframe opt-out code will no longer be generated by the UI as support for third party cookies in iframes is being discontinued by most major browsers.
- The methods
setExcludedReferrers
andgetExcludedReferrers
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.
- The user management UI no longer allows direct creation of a new user (with a password). Instead an invitation can be sent via email. Directly creating a new user is still possible using the API.
- A general config setting
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.
-
Added new event
UsersManager.inviteUser.end
, which is triggered after a new user has been invited -
Added new event
UsersManager.inviteUser.resendInvite
, which is triggered after the invitation to a user has been resent -
Added new event
UsersManager.inviteUser.accepted
, which is triggered after an invitation has been accepted -
Added 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.
- As access to files like
plugin.json
might reveal version details,json
files will now longer be considered as static files that can be served safely. Thereforejson
will no longer be included in the list of static file extensions in generated.htaccess
files.
- The config setting
enable_default_location_provider
inTracker
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.
- Added new event
Segment.filterSegments
. Plugins can use this to filter segment definitions.
- The
piwik-field
and related directives have been converted to Vue and thetemplate-file
attribute is now considered deprecated and will be removed in Matomo 5. Instead, thecomponent
property should be used to add a new form field, it should be an object with two properties that reference a Vue component,plugin
andname
, whereplugin
is the plugin the Vue component is located in andname
is the Vue name of the component's export.
- Plugins can now provide a list of changes which will be displayed as part of the "What's New?" menu notification. Learn more about how this works in the developer guide.
- We have begun introducing Vue 3 as the frontend framework to replace AngularJS. You can learn more about it in our developer guide.
- New API Methods
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 membersecurityPolicy
so plugins can use$this->securityPolicy
to access these new methods when a custom Content Security Policy is needed.
- With the introduction of Vue 3 we are also dropping support for IE11. All new supported browsers are determined by the browserslist tool. Running
npx browserslist
will list the browsers currently supported. - When the Ecommerce feature is disabled for a site, then the Live API no longer returns the Ecommerce related visitor properties
totalEcommerceRevenue
,totalEcommerceConversions
,totalEcommerceItems
,totalAbandonedCartsRevenue
,totalAbandonedCarts
andtotalAbandonedCartsItems
. - Content Security Policy (added in Matomo 4.4.0) is no longer in Report Only mode by default.
- The config setting
contact_email_address
inGeneral
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.
- The
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 settinglogin_allow_logme = 0
inGeneral
section ofconfig.ini.php
. - The redirect using the
url
param for the automatic login actionlogme
, will no longer do redirects to untrusted hosts. If you need to do redirects to other URLs on purpose, please add the according hosts astrusted_hosts
entry inconfig.ini.php
- When determining the client IP address from proxy headers like X-Forwarded-For, Matomo will by default look at the first IP in the list. If you need to read the last IP instead, the new INI config option
[General] proxy_ip_read_last_in_list
be set to1
. Using the last IP can be more secure when you are using proxy headers in combination with a load balancer. - Matomo logs can now be written into "errorlog" (logs using the error_log() php function) and "syslog" (logs to the syslog service) (to complement existing log writers: "screen", "file", "database"). Learn more.
- Added new command
core:version
which returns the Matomo version number.
- Added new command
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).
- Before the JS tracker method,
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 theaddListener
method to add event listener manually after the DOM has changed and theenableLinkTracking
is turned on we will track the click event for that element twice.
- Before every JS error was tracked, from this version the same JS error will be only tracked once per page view. If the very same error is happening multiple times, then it will be tracked only once within the same page view. If another page view is tracked or when the page reloads, then the error will be tracked again.
- It's no longer possible to store any class instances directly in the session object. Please use arrays or plain data instead.
- In Matomo 4.3.0 we have added a 'passwordConfirmation' parameter to the CorePluginsAdmin.setSystemSettings API method. It is currently optional, but will become mandatory in version 4.4.0. Plugin developers and users of the API should make sure to update their plugins and apps before this happens.
- The
password_hash_algorithm
,password_hash_argon2_threads
,password_hash_argon2_memory_cost
andpassword_hash_argon2_time_cost
INI config options have been added to allow using specificpassword_hash
algorithms and options if desired. - The
enable_php_profiler
INI config option was added. This must now be set to 1 before profiling is allowed in Matomo.
- A config setting
geolocation_download_from_trusted_hosts
was introduced. Downloading GeoIP databases will now be limited to those configured hosts only.
- The config settings
login_password_recovery_email_address
andlogin_password_recovery_name
have been removed to avoid possible smtp problems when sending recovery mails.noreply_email_address
andnoreply_email_name
will be used instead.
- Matomo no longer polyfills the
JSON
object in the JavaScript tracker. This means IE7 and older, Firefox 3 and older will be no longer suppported in the tracker. - The JavaScript tracker now uses
sendBeacon
by default if supported by the browser. You can disable this by calling the tracker methoddisableAlwaysUseSendBeacon
. 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. - The JS tracker event
PiwikInitialized
has been renamed toMatomoInitialized
- Support for tracking and reporting of these browser plugins has been discontinued: Gears, Director
- Plugins that extend the JS tracker should now add their callback to
matomoPluginAsyncInit
instead ofpiwikPluginAsyncInit
- The visitor ID cookie now contains less data (due to the _idvc, _idts, _viewts and _ects tracking parameters no longer being used). This is a breaking change if you use the Matomo PHP Tracker and forward the visitor cookie to it, and you will need to upgrade the PHP tracker to use with Matomo 4.
- The tracker method
setVisitStandardLength
has been removed as there is no need for it anymore. - The tracker method
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.
- The JS Tracker method
getPiwikUrl
has been deprecated andgetMatomoUrl
should be used instead. - The JS Tracker init method
piwikAsyncInit
has been deprecated andmatomoAsyncInit
should be used instead. - The JS object
window.Piwik
has been deprecated andwindow.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:
- If using the
piwik_ignore
css class to ignore outlinks we recommend replacing it withmatomo_ignore
- If using the
piwik_download
css class to mark a link as download we recommend replacing it withmatomo_download
- If using content tracking, we recommend replacing the following CSS classes should they be used
piwikTrackContent
,piwikContentPiece
,piwikContentTarget
, andpiwikContentIgnoreInteraction
withmatomoTrackContent
,matomoContentPiece
,matomoContentTarget
, andmatomoContentIgnoreInteraction
. - We also encourage using the
matomo.js
JS tracker file instead ofpiwik.js
andmatomo.php
tracker endpoint instead ofpiwik.php
endpoint.
- A new JS tracker method
getMatomoUrl
has been added which replacesgetPiwikUrl
.
- The
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 theJSON
renderer. - The
JSON
renderer now behaves like the previousJSON2
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:- API.getSettings
- Annotations.get
- Goals.getGoal
- UsersManager.getUser
- UsersManager.getUserByEmail
- SitesManager.getSiteFromId
- The API response format
php
has been removed. - The response of an individual request within the bulk request of
API.getBulkRequest
may change if the API returns a scalar value (eg5
). In this case the response will be no longer5
but for example{value: 5}
- The API method
UsersManager.getTokenAuth
has been removed. Instead you need to useUsersManager.createAppSpecificTokenAuth
and store this token in your application. - The API method
UsersManager.createTokenAuth
has been removed. Instead you need to useUsersManager.createAppSpecificTokenAuth
and store this token in your application. - The API method
DevicesDetection.getBrowserFamilies
has been removed. Instead you need to useDevicesDetection.getBrowsers
- The API method
CustomPiwikJs.doesIncludePluginTrackersAutomatically
has been renamed toCustomJsTracker.doesIncludePluginTrackersAutomatically
- The API method
Live.getLastVisitsForVisitor
has been removed. UseLive.getVisitorProfile
instead. - The API method
Live.getLastVisits
has been removed. UseLive.getLastVisitsDetails
instead. - These API methods have been removed:
API.getDefaultMetricTranslations
,API.getLogoUrl
,API.getHeaderLogoUrl
,API.getSVGLogoUrl
,API.hasSVGLogo
- These API methods have been removed:
SitesManager.getSitesIdWithVisits
,SitesManager.isSiteSpecificUserAgentExcludeEnabled
,SitesManager.setSiteSpecificUserAgentExcludeEnabled
- These API methods have been removed:
Referrers.getKeywordsForPageUrl
andReferrers.getKeywordsForPageTitle
. UseReferrers.getKeywords
instead in combination with aentryPageUrl
orentryPageTitle
segment. - The parameter
alias
from the API methodsUsersManager.addUser
andUsersManager.updateUser
has been removed.
- An optional new tracking parameter called
ca
has been added which can be used for tracking requests that aren't page views see #16569
- Added new event
Db.getTablesInstalled
, plugins should use to register the tables they create.
- The event
CustomPiwikJs.piwikJsChanged
has been renamed toCustomJsTracker.trackerJsChanged
- The event
CustomPiwikJs.shouldAddTrackerFile
has been renamed toCustomJsTracker.shouldAddTrackerFile
- The event
CustomMatomoJs.shouldAddTrackerFile
has been renamed toCustomJsTracker.manipulateJsTracker
- The event
Live.getAllVisitorDetails
has been removed. Use aVisitorDetails
class instead (see Live plugin). - The event
Live.getExtraVisitorDetails'
has been removed. Use theVisitorDetails
class within each plugin instead. - The event
Piwik.getJavascriptCode
has been renamed toTracker.getJavascriptCode
. - The event
LanguageManager.getAvailableLanguages
has been removed. UseLanguagesManager.getAvailableLanguages
instead. - The
$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.
- The method
\Piwik\Plugin::getListHooksRegistered()
has been removed. Use\Piwik\Plugin::registerEvents()
instead - The method
\Piwik\Piwik::doAsSuperUser()
has been removed. Use\Piwik\Access::doAsSuperUser()
instead - The method
\Piwik\SettingsPiwik::isPiwikInstalled()
has been removed. Use\Piwik\SettingsPiwik::isMatomoInstalled()
instead - The method
\Piwik\Updates::getSql()
has been removed. Use\Piwik\Updates::getMigrations()
instead - The method
\Piwik\Updates::getMigrationQueries()
has been removed. Use\Piwik\Updates::getMigrations()
instead - The method
\Piwik\Updates::executeMigrationQueries()
has been removed. Use\Piwik\Updates::executeMigrations()
instead - The method
\Piwik\Updates::update()
has been removed. Use\Piwik\Updates::doUpdate()
instead - The method
\Piwik\Updater::updateDatabase()
has been removed. The method is not needed anymore. - The method
\Piwik\Common::json_encode()
has been removed. Usejson_encode()
instead - The method
\Piwik\Common::json_decode()
has been removed. Usejson_decode()
instead - The method
\Piwik\Common::getContinentsList()
has been removed. Use\Piwik\Intl\Data\Provider\RegionDataProvider::getContinentList()
instead - The method
\Piwik\Common::getCountriesList()
has been removed. Use\Piwik\Intl\Data\Provider\RegionDataProvider::getCountriesList()
instead - The method
\Piwik\Common::getLanguagesList()
has been removed. Use\Piwik\Intl\Data\Provider\LanguageDataProvider::getLanguagesList()
instead - The method
\Piwik\Common::getLanguageToCountryList()
has been removed. Use\Piwik\Intl\Data\Provider\LanguageDataProvider::getLanguageToCountryList()
instead - The method
\Piwik\Site::getCurrencyList()
has been removed. Use\Piwik\Intl\Data\Provider\CurrencyDataProvider::getCurrencyList()
instead - The method
\Piwik\Piwik::setUserHasSuperUserAccess()
has been removed. Use\Piwik\Access::doAsSuperUser()
instead - The class
\Piwik\MetricsFormatter
has been removed. UsePiwik\Metrics\Formatter
orPiwik\Metrics\Formatter\Html
instead - The class
\Piwik\Registry
has been removed. Use\Piwik\Container\StaticContainer
instead - The class
\Piwik\TaskScheduler
has been removed. Use\Piwik\Scheduler\Scheduler
instead - The class
\Piwik\DeviceDetectorFactory
has been removed. Use\Piwik\DeviceDetector\DeviceDetectorFactory
instead - The class
\Piwik\ScheduledTask
has been removed. Use\Piwik\Scheduler\Task
instead. - The class
\Piwik\Translate
has been removed. Use\Piwik\Translation\Translator
instead. - The class
\Piwik\Plugins\Login\SessionInitializer
is no longer considered API as it is no longer needed. - The class
\Piwik\Container\StaticContainer
still exists but we no longer consider it an API and constructor injection should be used instead where possible. - The method
Piwik\Columns\Dimension::factory
has been removed. UseDimensionsProvider::factory
instead. - The method
Piwik\Config::reset
has been removed. Use thereload
method instead. - The method
Piwik\Config::init
has been removed. Use thereload()
method instead. - The method
Piwik\Db::getColumnNamesFromTable
has been removed. Use theTableMetadata::getColumns
method instead. - The method
Piwik\Session\SessionInitializer::getHashTokenAuth
has been removed. There is no need for this method anymore. - The method
Piwik\Tracker::getDatetimeFromTimestamp
has been removed. UsePiwik\Date::getDatetimeFromTimestamp
instead. - The method
Dimension::addSegment()
has been removed. See new implementation ofDimensionSegmentFactory::createSegment
for a replacement - The constant
Piwik\Plugins\Goals\API::NEW_VISIT_SEGMENT
has been removed. UsePiwik\Plugins\VisitFrequency\API::NEW_VISITOR_SEGMENT
instead. - The signature of
Dimension::configureSegments()
has been changed. Similar to configuring Metrics it now takes two parametersSegmentsList $segmentsList
andDimensionSegmentFactory $dimensionSegmentFactory
. - The signature of the event
Segment.addSegments
has been changed. It now has one parameterSegmentsList $list
, which allows adding new segments to the list - The core plugin
CustomPiwikJs
has been renamed toCustomJsTracker
- The class
Piwik\Plugins\CustomPiwikJs\TrackerUpdater
has been renamed toPiwik\Plugins\CustomJsTracker\TrackerUpdater
- The method
Piwik\Cookie::set
no longer accepts an array as value Zend_Validate
and all subclasses have been completely removed.- Matomo's mail component (
Piwik\Mail
) has been rewritten:- Zend_Mail has been removed.
Piwik\Mail
is now an independet class. - PHPMailer is now used for sending mails in
\Piwik\Mail\Transport
and can be replaced using DI. - Various methods in
Piwik\Mail
have been removed or changed their signature.
- Zend_Mail has been removed.
- A new API
UsersManager.createAppSpecificTokenAuth
has been added to create an app specific token for a user. - A new method
Common::hashEquals
has been added for timing attack safe string comparisons. - Reporting API: It is now possible to apply
hideColumns
recursively to nested values by settinghideColumnsRecursively=1
. For allLive
api methods this is the default behaviour.
- When embedding reports (widgets) into a different site, it is no longer possible to use authentication tokens of users with at least write access, unless the
[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 withview
access and use the token of this user to embed the report. - The log importer in
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. - Deprecated
piwik
font was removed. Usematomo
font instead - The JavaScript AjaxHelper does not longer support synchronous requests. All requests will be sent async instead.
- The console option
--piwik-domain
has been removed. Use--matomo-domain
instead - The controller action
Proxy.redirect
has been removed. Instead link to the URL directly in HTML and set an attributerel="noreferrer noopener"
- GeoIP Legacy support has been fully removed. Users of GeoIP Legacy need to set up a new location provider like GeoIP2, otherwise the default location provider will be used.
- Site search category and count are no longer stored as custom variables. That also means they will now have an extra field in action details and no longer appear in custom variables.
- The dimension and
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. - The metric (avg.) page generation time has been deprecated. It is no longer possible to track it. Already tracked values will still be shown in old reports. More detailed performance metrics are now available in PagePerformance plugin.
- Added support for campaign name parameter
matomo_campaign
/mtm_campaign
and campaign keyword parametermatomo_kwd
/mtm_kwd
- The following dimensions have been removed and replaced with versions that measure seconds: visitor_days_since_first, visitor_days_since_last, visitor_days_since_order
- The _idvc, _idts, _viewts and _ects tracker parameters are no longer used, the values are calculated server side. Note: tracking these values server side means replaying log data in the past will result in inaccurate values for these dimensions.
- The Dependency Injection library PHP-DI was updated. Some definitions need to be updated:
- The Method
\DI\object()
has been removed. You can use\DI\autowire()
or\DI\create()
instead. - The Method
\DI\link()
has been removed. Use\DI\get()
instead. - Defining global observer functions in config now requires the functions to be wrapped in
\DI\value()
, unless they are a factory.
- The Method
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).- For more info on consent have a look at https://developer.matomo.org/guides/tracking-javascript-guide#asking-for-consent
- The first parameter
userLogin
in theUsersManager.getUserPreference
method is now optional and defaults to the currently authenticated user login.
- A new event
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.
- The methods
\Piwik\Plugins\SitesManager\isSiteSpecificUserAgentExcludeEnabled()
and\Piwik\Plugins\SitesManager\setSiteSpecificUserAgentExcludeEnabled()
have been deprecated. - The method
\Piwik\SettingsServer::isMatomoForWordPress()
has been added so plugins can detect if the plugin is being executed within Matomo for WordPress or Matomo On-Premise
- New tracker method
setVisitStandardLength
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. - Added new event
Metrics.isLowerValueBetter
so plugins can define if lower metric values are better for additional metrics.
- User ID is no longer linked to visitor ID. Actions with different user IDs will still be considered as part of different visits, irrespective of their visitor IDs, but the same visitor ID can be used with different user IDs.
- Added new event
Visualization.beforeRender
, triggered after immediately before rendering a visualization. - Added new event
Http.sendHttpRequest
andHttp.sendHttpRequest.end
so plugins can listen to external HTTP requests, monitor them, or resolve the request themselves. - Added new event
CliMulti.supportsAsync
so plugins can force or disable the usage of archiving through the CLI
- When giving a user superuser access through the
UsersManager.setSuperUserAccess
API, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request. - Website referrer URLs are now detected using domain only instead of domain and path. This means if you have two different websites on the same domain, but different paths, and a visitor visits from one to the other, it won't have a referrer website set.
- Custom Dimensions values set with
setCustomDimension
are now URL encoded (they previously weren't). If you were manually URL encoding the custom dimension values before callingsetCustomDimension
, 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.
- A new tracker method
ping
has been added to send a ping request manually instead of using the heart beat timer. - Added new event
ViewDataTable.configure.end
, triggered after view configuration properties have been overwritten by saved settings and query parameters.
Referrers.getKeywordsForPageUrl
andReferrers.getKeywordsForPageTitle
APIs have been deprecated and will be removed in Matomo 4.0.0- By default, Matomo application logs will now be logged in
tmp/logs/matomo.log
instead oftmp/logs/piwik.log
. This log file path can be edited in your config/config.ini.php in the INI settinglogger_file_path
.
- It is now possible to locate plugins in a custom directory by setting an environment variable
MATOMO_PLUGIN_DIRS
or a$GLOBALS['MATOMO_PLUGIN_DIRS']
variable in$MATOMO_ROOT/bootstrap.php
. - It is now possible to use monolog's FingersCrossedHandler which buffers all logs and logs all of them in case of warning or error.
- New API methods
Piwik\Plugin\Manager::getPluginsDirectories()
andPiwik\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. - A new tracker method
disableQueueRequest
has been added to disable queued requests which may be useful when logs are imported. - The event
LanguageManager.getAvailableLanguages
has been deprecated. UseLanguagesManager.getAvailableLanguages
instead.
- When changing the email address or the password through the
UsersManager.updateUser
API, a new parameterpasswordConfirmation
needs to be sent along with the request containing the current password of the user issuing the API request. - The output type "save on disk" in the API method
ScheduledReport.generateReport
has been replaced by the download output type. - The method
Piwik\Piwik::doAsSuperUser
has been deprecated and will be removed in Matomo 4. UsePiwik\Access::doAsSuperUser
instead.
- It is now possible to queue a request on the JavaScript tracker using the method
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. - When specifying a callback in the JavaScript tracker in a tracker method, we now make sure to execute the callback even in error cases or when sentBeacon is used. The callback receives an event parameter to determine which request was sent and whether the request was sent successfully.
- Added new event
Metrics.getEvolutionUnit
which lets you set the unit for a metric used in evolution charts and row evolution.
- The log importer now supports the
--tracker-endpoint-path
parameter which allows you to use a different tracker endpoint than/piwik.php
, if desired. - It is now possible to define different log levels for different log writers via INI config. Set log_level_file, for example, to set the log level for the file writer, or log_level_screen for the screen writer.
- New Matomo installation will now use by default "matomo.js" and "matomo.php" as tracking endpoints. From Matomo 4.0 all installations will use "matomo.js" and "matomo.php" by default. We recommend you ensure those files can be accessed through the web and are not blocked.
- The method
Piwik\SettingsPiwik::isPiwikInstalled()
has been deprecated and renamed toisMatomoInstalled()
. It is still supported to use the method, but the method will be removed in Piwik 4.0.0
- Added new event
Access.modifyUserAccess
which lets plugins modify current user's access levels/permissions. - Added new event
CustomMatomoJs.manipulateJsTracker
which lets plugins modify the JavaScript tracker.
- Logging to a file can now be easily enabled during tests. A new
[tests] enable_logging
INI option has been added, which you can set to1
to enable logging for all tests. Thetests:run
andtests:run-ui
commands now both have an--enable-logging
option to enable logging for a specific run.
- A new role has introduced called "write" which has less permissions than an admin but more than a view only user (see FAQ).
- Custom currencies can now be added using the
currencies[]
configuration key. - A new segment
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 thearchive_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.
- New parameter
--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.
- Added new event
API.addGlossaryItems
which lets you add items to the glossary. - Added new event
Tracker.detectReferrerSocialNetwork
which lets you add custom social network detections - Added new event
Report.unsubscribe
which is triggered whenever someone unsubscribe from a report - Added new API method
UsersManager.getAvailableRoles
to fetch a list of all available roles that can be granted to a user. - Added new API method
UsersManager.getAvailableCapabilities
to fetch a list of all available capabilities that can be granted to a user. - Added new API method
UsersManager.addCapabilities
to grant one or multiple capabilities to a user. - Added new API method
UsersManager.removeCapabilities
to remove one or multiple capabilities from a user. - The API method
UsersManager.setUserAccess
now accepts an array to pass a role and multiple capabilities at once. - Plugin classes can overwrite the method
requiresInternetConnection
to define if they should be automatically unloaded if no internet connection is available (enable_internet_features = 0) - Added two new methods to the JS tracker:
removeEcommerceItem
andclearEcommerceCart
to allow better control over what is in the ecommerce cart. - Tracking API requests now include
&consent=1
in the Tracking API URL When consent has been given by a user.
- Changed some menu items to use translation keys instead (see PR #12885).
- The methods
assertResponseCode()
andassertHttpResponseText()
inPiwik\Tests\Framework\TestCase\SystemTestCase
have been deprecated and will be removed in Matomo 4.0. Please usePiwik\Http
instead. - The classes
PHPUnit\Framework\Constraint\HttpResponseText
andPHPUnit\Framework\Constraint\ResponseCode
have been deprecated and will be removed in Matomo 4.0. Please usePiwik\Http
instead. - Creating links through the Proxy has been deprecated. Use rel="" instead.
- The console option
--piwik-domain
has been deprecated and will be removed in Matomo 4.0. Use--matomo-domain
instead - Social networks are now detected as new referrer type (ID=7), which allows improved reports and better segmentation
- New settings form field UI component "Field Array" that lets users enter multiple values for one setting as a flat array
- Added new method
Piwik\API\Request::isRootRequestApiRequest()
to detect if the root request is an API request.
- Flattened action url reports now always include a leading
/
and will no longer include thedefault_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.
- New JavaScript tracker functions to ask for consent:
requireConsent
,rememberConsentGiven
,setConsentGiven
,forgetConsentGiven
.
- New events
PrivacyManager.deleteLogsOlderThan
,PrivacyManager.exportDataSubjects
andPrivacyManager.deleteDataSubjects
to enable plugins to be GDPR compliant. - New event
AssetManager.addStylesheets
to add additional less styles which are not located in a file. - New event
Archiving.getIdSitesToMarkArchivesAsInvalidated
that lets plugins customize the behaviour of report invalidations. - Reports and visualizations can now disable the 'all' rows limit selector:
$view->config->disable_all_rows_filter_limit
. - New settings form field UI component "Multi Tuple" that lets users enter multiple values for one setting
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
- A new JavaScript tracker method
resetUserId
has been added to allow clearing user and visitor id. - A new event
Actions.addActionTypes
has been added, to allow plugins to add their custom action types. - Dashboard API has been extended by the methods
copyDashboardToUser
,createNewDashboardForUser
,removeDashboard
andresetDashboardLayout
- It is also now possible to delete the first dashboard for a user for automation purposes. Doing so and not adding a new first dashboard might result in buggy UX.
getDashboards
API method has been extended by additional parameters to fetch dashboards for specific user
- A new event
API.Request.intercept
has been added which allows plugins to intercept API requests to perform custom logic, overriding the original API method. - A new event
Request.shouldDisablePostProcessing
has been added which allows plugins to disable DataTable post processing for individual API requests. - A new event
SitesManager.shouldPerformEmptySiteCheck
has been added to allow plugins to disable the empty site check for individual sites. - A new JavaScript tracker method
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.
- New HTTP API
API.getMatomoVersion
was introduced. The previous HTTP APIAPI.getPiwikVersion
will still work but will now be hidden from the API reference page.
- The
historyService
along withbroadcast.init
,broadcast.propagateAjax
,broadcast.pageLoad
have been deprecated and will be removed in Piwik 4.
- Themes can now customize the header text color using
@theme-color-header-text
- New event
Widgetize.shouldEmbedIframeEmpty
added so plugins can optionally define the output of the widgetized HTML themselves - New events added to add and filter visitor details:
Live.addProfileSummaries
andLive.filterProfileSummaries
- New JavaScript method
piwikHelper.registerShortcut
allows plugins to bind keyboard shortcuts. A summary for available shortcuts will be shown by pressing?
- New Segment added:
visitStartServerMinute
for Server time - minute (Start of visit) - New Segment added:
visitEndServerMinute
for Server time - minute (End of visit) - New events added to add and filter visitor details:
Live.addVisitorDetails
andLive.filterVisitorDetails
- Reports and visualizations can now hide the export icons with a new property
$view->config->show_export
. - Reports and visualizations can now show a message above the report with a new property
$view->config->show_header_message
. - The following events have been added:
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 metrics
- The following new API classes have been added:
Piwik\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 dimension
- New config.ini.php setting
show_update_notification_to_superusers_only
makes it possible to hide update notifications for all users except of superusers
- The event
Live.getAllVisitorDetails
has been deprecated and will be removed in Piwik 4. Use aVisitorDetails
class instead (see Live plugin).
- New method
setSecureCookie
that sets the cookie's secure parameter
- The events
ScheduledTasks.shouldExecuteTask
,ScheduledTasks.execute
,ScheduledTasks.execute.end
have been added to customize the behaviour of scheduled tasks. - A new event
CustomPiwikJs.shouldAddTrackerFile
has been added to let plugins customize which tracker files should be included in piwik.js JavaScript tracker - A new event
Login.authenticate.successful
has been added, which is triggered when a user successful signs in - A new API class
Piwik\Plugins\CustomPiwikJs\TrackerUpdater
has been added to update the piwik.js JavaScript tracker
- The commands
plugin:activate
andplugin:deactivate
can now activate and deactivate multiple plugins at once
- A new event
Db.getActionReferenceColumnsByTable
has been added in case a plugin defines a custom log table which references data to the log_action table - The event
System.addSystemSummaryItems
andSystem.filterSystemSummaryItems
have been added so plugins can add items and filter items of the system summary widget - A new JavaScript tracker method
getPiwikUrl
has been added to retrieve the URL of where the Piwik instance is located - A new JavaScript tracker method
getCurrentUrl
has been added to retrieve the current URL of the website. - A new JavaScript tracker method
getNumTrackedPageViews
has been added to retrieve the number of tracked page views within the currently loaded page or web application. - New JavaScript tracker methods
setSessionCookie
,getCookie
,hasCookies
,getCookieDomain
,getCookiePath
, andgetSessionCookieTimeout
have been added for better cookie support in plugins. email
andurl
form fields can now be used in settings.
- New config setting
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. - New Report class property
Report::$supportsFlatten
lets you define if a report supports flattening (defaults totrue
). If set tofalse
it will also setViewDataTable\Config::$show_flatten_table
tofalse
- A new event
Controller.triggerAdminNotifications
has been added to let plugins know when they are supposed to trigger notifications in the admin.
- pChart library has been removed in favor of CpChart, a pChart fork with composer support and PSR standards.
- A new SMS provider for sms reports has been added: ASPSMS.com
- The JavaScript Tracker now supports CrossDomain tracking. The following tracker methods were added for this:
enableCrossDomainLinking
,disableCrossDomainLinking
,isCrossDomainLinkingEnabled
- Added JavaScript Tracker method
getLinkTrackingTimer
to get the value of the configured link tracking time - Added JavaScript Tracker method
deleteCustomVariables
to delete all custom variables within a certain scope - The method
enableLinkTracking
can now be called several times to make Piwik aware of newly added links when your DOM changes - Added a new method
Piwik\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. - The event
Tracker.newConversionInformation
now posts a new fourth parameter$action
- New HTTP API method
UserCountry.getCountryCodeMapping
to get a list of used country codes to country names
- SMS provider now can define their credential fields by overwriting
getCredentialFields()
. This allows to have SMS providers that require more than only an API key. - Therefore the MobileMessaging API method
setSMSAPICredential()
now takes the second parameter as an array filled with credentials (instead of a string containing an API key)
- Live API responses now return a new field ‘generationTimeMilliseconds’ (the generation time for this page, in milliseconds) which is internally used to process the Average generation time in the Visitor Profile
- Added new event
MultiSites.filterRowsForTotalsCalculation
to filter which sites will be included in the All Websites Dashboard totals calculation. - The method
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.
-
When using the Piwik JavaScript Tracking via
_paq.push
, it is now required to configure the tracker (eg callingsetSiteId
andsetTrackerUrl
) before thepiwik.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. [...]" -
The UserManager API methods do no longer return any
token_auth
properties when requesting a user -
The menu classes
Piwik\Menu\MenuReporting
andPiwik\Menu\MenuMain
have been removed -
The class
Piwik\Plugin\Widgets
has been removed and replaced byPiwik\Widget\Widget
. For each widget one class is needed from now on. You can generate a widget via./console generate:widget
. -
The class
Piwik\WidgetList
class has been moved toPiwik\Widget\WidgetsList
. -
The method
Piwik\Plugins\API\API::getLastDate()
has been removed. -
The method
Piwik\Archive::getDataTableFromArchive()
has been removed, usePiwik\Archive::createDataTableFromArchive
instead. -
The method
Piwik\Plugin\Menu::configureReportingMenu
has been removed. To add something to the reporting menu you need to create widgets -
The method
Report::configureWidget()
,Report::getWidgetTitle()
andReport::configureReportingMenu()
have been removed, use the new methodReport::configureWidgets()
instead. -
The method
Report::getCategory()
has been moved toReport::getCategoryId()
and does no longer return the translated category but the translation key of the category. -
The property
Report::$category
has been renamed toReport::$categoryId
-
The methods
Report::factory()
,Report::getAllReportClasses()
,Report::getAllReports
have been moved to thePiwik\Plugin\Reports
class. -
The properties
Report::$widgetTitle
,Report::$widgetParams
andReport::$menuTitle
were removed, use the methodReport::configureWidgets()
to create widgets instead -
In the HTTP API methods
Dashboard.getDefaultDashboard
andDashboard.getUserDashboards
we do no longer remove not existing widgets as it is up to the client which widgets actually exist -
The method
Piwik\Plugin\Controller::getEvolutionHtml
has been removed without a replacement as it should be no longer needed. The evolution is generated by ViewDataTables directly -
The
core:plugin
console command has been removed in favor of the newplugin:list
,plugin:activate
andplugin:deactivate
commands as announced in Piwik 2.11 -
The visibility of private properties and methods in
Piwik\Plugins\Login\Controller
were changed toprotected
-
Controller actions are now case sensitive. This means the URL and events have to use the same case as the name of the action defined in a controller.
-
When calling the HTTP Reporting API, a default filter limit of 100 is now always applied. The default filter limit used to be not applied to API calls that do not return reports, such as when requesting sites, users or goals information.
-
The "User Menu" was removed and should be replaced by "Admin Menu". Change
configureUserMenu(MenuUser $menu)
toconfigureAdminMenu(MenuAdmin $menu)
in yourMenu.php
. -
The method
Piwik\Menu\MenuAbstract::add()
has been removed, usePiwik\Menu\MenuAbstract::addItem()
instead -
The method
Piwik\Menu\MenuAdmin::addSettingsItem()
was removed, usePiwik\Menu\MenuAdmin::addSystemItem()
instead. -
A new method
Piwik\Menu\MenuAdmin::addMeasurablesItem()
was added. -
The class
Piwik\Plugin\Settings
has been split toPiwik\Settings\Plugin\SystemSettings
andPiwik\Settings\Plugin\UserSettings
. -
The creation of settings has slightly changed to improve performance. It is now possible to create new settings via the method
$this->makeSetting()
seePiwik\Plugins\ExampleSettingsPlugin\SystemSettings
for an example. -
It is no longer possible to define an introduction text for settings.
-
If requesting multiple periods for one report, the keys that define the range are no longer translated. For example before 3.0 an API response may contain:
<result date="From 2010-02-01 to 2010-02-07">
which is now<result date="2010-02-01,2010-02-07">
. -
The following deprecated events have been removed as mentioned.
-
Tracker.existingVisitInformation
Use dimensions instead of usingTracker
events. -
Tracker.newVisitorInformation
-
Tracker.recordAction
-
Tracker.recordEcommerceGoal
-
Tracker.recordStandardGoals
-
API.getSegmentDimensionMetadata
Define segments in Dimension instead -
Menu.Admin.addItems
Create a Menu instead of usingMenu
events -
Menu.Reporting.addItems
-
Menu.Top.addItems
-
ViewDataTable.addViewDataTable
Create a Visualization instead -
ViewDataTable.getDefaultType
Specify the default type in a Report instead -
Login.authenticate
Create a custom SessionInitializer instead of usingLogin
events -
Login.initSession.end
-
Login.authenticate.successful
-
When posting one of the events
API.Request.dispatch
,API.Request.dispatch.end
,API.$plugin.$apiAction
, orAPI.$plugin.$apiAction.end
the$finalParameters
parameter is indexed in Piwik 2 (egarray(1, 6)
), and named in Piwik 3 (egarray('idSite' => 1, 'idGoal' => 6)
) -
Widgets using the already removed
UserSettings
plugin won't work any longer. Please update the module and action parameter in the widget url according to the following listold 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.
- The method
Piwik\Updates::getMigrationQueries()
has been deprecated and renamed togetMigrations()
. It is still supported to use the method, but the method will be removed in Piwik 4.0.0 - The method
Piwik\Updater::executeMigrationQueries()
has been deprecated and renamed toexecuteMigrations
. It is still supported to use the method, but the method will be removed in Piwik 4.0.0.
- Multiple widgets for one report can now be created via the
Report::configureWidgets()
method via the new classesPiwik\Widget\ReportWidgetFactory
andPiwik\Widget\ReportWidgetConfig
- There is a new property
Report::$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 methodReport::getSubCategory()
lets you get this value. - The new classes
Piwik\Widget\Widget
,Piwik\Widget\WidgetConfig
andPiwik\Widget\WidgetContainerConfig
lets you create a new widget. - The new class
Piwik\Category\Subcategory
let you change the name and order of menu items - New HTTP API method
API.getWidgetMetadata
to get a list of available widgets - New HTTP API method
API.getReportPagesMetadata
to get a list of all available pages that exist including the widgets they include - New HTTP API method
SitesManager.getSiteSettings
to get a list of all available settings for a specific site - The JavaScript AjaxHelper has a new method
ajaxHelper.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. - The new class
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
. - The new method
Piwik\Updater::executeMigration
lets you execute a single migration. - The new method
Piwik\Segment::willBeArchived
lets you detect whether a segment will be archived or not. - The following events have been added:
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 uninstalled- New HTTP Tracking API parameter
pv_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; - New event
Segment.addSegments
that lets you add segments. - New Piwik JavaScript Tracker method
disableHeartBeatTimer()
to disable the heartbeat timer if it was previously enabled. - The
SitesManager.getJavascriptTag
has a new optiongetJavascriptTag
to enable the tracking of users that have JavaScript disabled
- New now accept tracking requests for up to 1 day in the past instead of only 4 hours
- If a tracking request has a custom timestamp that is older than one day and the tracking request is not authenticated, we ignore the whole tracking request instead of ignoring the custom timestamp and still tracking the request with the current timestamp
- Piwik JavaScript Tracking API: we now attempt to track Downloads and Outlinks when the user uses the mouse middle click or the mouse right right click. Previously only left clicks on Downloads and Outlinks were measured.
- New "Sparklines" visualization that lets you create a widget showing multiple sparklines.
- New config.ini.php setting:
tracking_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.
- Updated AngularJS from 1.2.28 to 1.4.3
- Updated several backend libraries to their latest version: doctrine/cache, php-di.
- Support for IE8 was dropped. This affects only the Piwik UI, not the Piwik.js Tracker.
- Required PHP version was increased from 5.3 to 5.5.9
- We have updated PhantomJS 1.9 to 2.1.1 for our UI screenshot tests.
- The Piwik JavaScript tracker has a new method
trackRequest
that allows you to send any tracking parameters to Piwik. For example_paq.push(['trackRequest', 'te=foo&bar=baz'])
- Expected screenshots for UI tests are now stored using Git LFS instead of a submodule. Running, creating or updating UI tests will require Git LFS to be installed.
The folder containing expected screenshots was renamed from
expected-ui-screenshots
toexpected-screenshots
. The UI-Test-Runner is now able to handle both names.
- Multiple JavaScript trackers can now be created easily via
_paq.push(['addTracker', piwikUrl, piwikSiteId])
. All tracking requests will be then sent to all added Piwik trackers. Learn more. - It is possible to get an asynchronously created tracker instance (
addTracker
) via the methodPiwik.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. - Added a new API method
Goals.getGoal($idSite, $idGoal)
to fetch a single goal.
- Piwik is now compatible with PHP7.
piwik.js
, if you call the methodsetDomains
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 tosetDomains
contain a path and if no host alias is already given for the current host alias. Say you are on "example.org" and sethostAlias = ['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 ecommerce order is tracked usingtrackEcommerceOrder
, the items in the cart will now be removed from the JavaScript object. CallingtrackEcommerceCartUpdate
will not remove the items in the cart.
- New method
setIsWritableByCurrentUser
forSystemSetting
to change the writable permission for certain system settings via DI. - JS Tracker:
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 Piwik - To customise the list of URL query parameters to be removed from your URLs, you can now define and overwrite
url_query_parameter_to_exclude_from_url
INI setting in yourconfig.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
.
- The following PHP functions have been deprecated and will be removed in Piwik 3.0:
SettingsServer::isApache()
- JavaScript Tracker: Measuring domains and/or sub-domains
- Reporting API: when a cell value in a CSV or TSV (excel) data export starts with a character
=
,-
or+
, Piwik will now prefix the value with'
to ensure that it is displayed correctly in Excel or OpenOffice/LibreOffice.
- Tracking API: by default, when tracking a Page URL, Piwik will now remove the URL query string parameter
sid
if it is found. - In the JavaScript tracker, the function
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.
- The setting
[General]enable_marketplace=0/1
was removed, instead the new plugin Marketplace can be disabled/enabled. The updater should automatically migrate an existing setting.
- New segment
actionType
lets you segment all actions of a given type, eg.actionType==events
oractionType==downloads
. Action types values are:pageviews
,contents
,sitesearches
,events
,outlinks
,downloads
- New segment
actionUrl
lets you segment any action that matches a given URL, whether they are Pageviews, Site searches, Contents, Downloads or Events. - New segment
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. - New segment operators
=^
"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. - The JavaScript Tracker method
PiwikTracker.setDomains()
can now handle paths. This means when setting eg_paq.push(['setDomains, '*.matomo.org/website1'])
all link that goes to the same domainmatomo.org
but to any other path thanwebsite1/*
will be treated as outlink. - In Administration > Websites, for each website, there is a checkbox "Only track visits and actions when the action URL starts with one of the above URLs". In Piwik 2.14.0, any action URL starting with one of the Alias URLs or starting with a subdomain of the Alias URL would be tracked. As of Piwik 2.15.0, when this checkbox is enabled, it may track less data: action URLs on an Alias URL subdomain will not be tracked anymore (you must specify each sub-domain as Alias URL).
- It is now possible to pass an option
php-cli-options
to thecore: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"
- New less variable
@theme-color-menu-contrast-textSelected
that lets you specify the color of a selected menu item. - in Administration > Diagnostics, there is a new page
Config file
which lets Super User view all config values fromglobal.ini.php
in the UI, and whether they were overridden in yourconfig/config.ini.php
- New command
config: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 atoken_auth
of a user withadmin
permission, the returned dataset will not include all usernames as previously, API will now only return usernames for users withview
oradmin
permission to website(s) viewable by thistoken_auth
.- When generating a new plugin skeleton via
generate:plugin
command, plugin name must now contain only letters and numbers. - JavaScript Tracker tests no longer require
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 inconfig/config.ini.php
. - The definitions for search engine and social network detection have been moved from bundled data files to a separate package (see https://github.com/matomo-org/searchengine-and-social-list).
- In UI screenshot tests, a test environment
configOverride
setting should be no longer overwritten. Instead new values should be added to the existingconfigOverride
array in PHP or JavaScript. For example instead oftestEnvironment.configOverride = {group: {name: 1}}
usetestEnvironment.overrideConfig('group', 'name', '1')
.
- Add your own SMS/Text provider by creating a new class in the
SMSProvider
directory of your plugin. The class has to extendPiwik\Plugins\MobileMessaging\SMSProvider
and implement the required methods. - Segments can now be composed by a union of multiple segments. To do this set an array of segments that shall be used for that segment
$segment->setUnionOfSegments(array('outlinkUrl', 'downloadUrl'))
instead of defining a SQL column.
- The method
DB::tableExists
was un-used and has been removed.
- New command
diagnostics:analyze-archive-table
that analyzes archive tables - New command
database:optimize-archive-tables
to optimize archive tables and possibly save disk space (even if on InnoDB) - New Command
core:invalidate-report-data
to invalidate archive data (w/ period cascading) (FAQ)
- Piwik 2.15.0 is now mostly compatible with PHP7.
- The JavaScript Tracker
piwik.js
got a new methodlogAllContentBlocksOnPage
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'])
- The Class
Piwik\Plugins\Login\Controller
is now considered a public API. - The new method
Piwik\Menu\MenuAbstract::registerMenuIcon()
can be used to define an icon for a menu category to replace the default arrow icon. - New event
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. - New events
CronArchive.init.start
which is triggered when the CLI archiver starts andCronArchive.end
when the archiver ended. - Piwik tracker can now be configured with strict Content Security Policy (CSP FAQ).
- Super Users can choose whether to use the latest stable release or latest Long Term Support release.
- The method
Dimension::getId()
has been set asfinal
. It is not allowed to overwrite this method. - We fixed a bug where the API 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. - Handling of localized date, time and range formats has been changed. Patterns no longer contain placeholders like %shortDay%, but work with CLDR pattern instead. You can use one of the predefined format constants in Date class for using getLocalized().
- As we are now using CLDR formats for all languages, some time formats were even changed in english. Attributes like prettyDate in API responses might so have been changed slightly.
- The config
enable_measure_piwik_usage_in_idsite
which is used to track the Piwik usage with Piwik was removed and replaced by a new pluginAnonymousPiwikUsageMeasurement
- The following HTTP API methods have been deprecated and will be removed in Piwik 3.0:
SitesManager.getSitesIdWithVisits
API.getLastDate
- The following events have been deprecated and will be removed in Piwik 3.0. Use dimensions instead.
Tracker.existingVisitInformation
Tracker.getVisitFieldsToPersist
Tracker.newConversionInformation
Tracker.newVisitorInformation
Tracker.recordAction
Tracker.recordEcommerceGoal
Tracker.recordStandardGoals
- The Platform API method
\Piwik\Plugin::getListHooksRegistered()
has been deprecated and will be removed in Piwik 4.0. Use\Piwik\Plugin::registerEvents()
instead.
- When logging in, the username is now case insensitive
- URLs with emojis and any other unicode character will be tracked, with special characters replaced with
�
- A permanent warning notification is now displayed when PHP is 5.4.* or older, since it has reached End Of Life
- In
piwik.js
we replaced JSON2 with JSON3 to implement CSP (Content Security Policy) as JSON3 does not useeval()
. JSON3 will be used if a browser does not provide a native JSON API. We are usingJSON3
in a way that it will not conflict if your website is usingJSON3
as well. - The option
branch
of the console commanddevelopment:sync-system-test-processed
was removed as it is no longer needed. - All numbers in reports will now appear formatted (eg.
1,000,000
instead of1000000
) - Database connections now use
UTF-8
charset explicitly to force UTF-8 data handling
- The
UserSettings
API has been removed. The API was deprecated in earlier versions. UseDevicesDetection
,Resolution
andDevicePlugins
API instead. - Many translations have been moved to the new Intl plugin. Most of them will still work, but please update their usage. See matomo-org#8101 for a full list
- The JavaScript Tracker does now track outlinks and downloads if a user opens the context menu if the
enabled
parameter of theenableLinkTracking()
method is set totrue
. To use this new feature usetracker.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. - The JavaScript Tracker now contains the 'heart beat' feature which can be used to obtain more accurate visit lengths by periodically sending 'ping' requests to Piwik. To use this feature use
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]);
. - New custom segment
languageCode
that lets you segment visitors that are using a particular language. Example values:de
,fr
,en-gb
,zh-cn
, etc. - Segment
userId
now supports any segment operator (previously only operator Contains=@
was supported for this segment).
- The command
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. - The command
scheduled-tasks:run
now has an argumenttask
that lets you force run a particular scheduled task.
- Updated pChart library from 2.1.3 to 2.1.4. The files were moved from the directory
libs/pChart2.1.3
tolibs/pChart
- To execute UI tests "ImageMagick" is now required.
- The Q JavaScript promise library is now distributed with tests and can be used in the piwik.js tests.
- The API method
Live.getLastVisitsDetails
does no longer support the API parameterfilter_sort_column
to prevent possible memory issues whenfilter_offset
is large. - The Event
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 usepiwik.php
for checks please usepiwik.php?rec=0
.
- The method
Piwik\Archive::getBlob()
has been deprecated and will be removed from June 1st 2015. Use one of the methodsgetDataTable*()
methods instead. - The API parameter
countVisitorsToFetch
of the API methodLive.getLastVisitsDetails
has been deprecated asfilter_offset
andfilter_limit
work correctly now.
- There is now a
diagnostic:run
command to run the system check from the command line. - There is now an option
--xhprof
that can be used with any command to profile that command via XHProf.
- Visitor details now additionally contain:
deviceTypeIcon
,deviceBrand
anddeviceModel
- In 2.6.0 we added the possibility to use
filter_limit
andfilter_offset
if an API returns an indexed array. This was not working in all cases and is fixed now. - The API parameter
filter_pattern
andfilter_offset[]
can now be used if an API returns an indexed array.
- The referrer spam filter has moved from the
referrer_urls_spam
INI option (inglobal.ini.php
) to a separate package (see https://github.com/matomo-org/referrer-spam-list).
- The deprecated method
Period::factory()
has been removed. UsePeriod\Factory
instead. - The deprecated method
Config::getConfigSuperUserForBackwardCompatibility()
has been removed. - The deprecated methods
MenuAdmin::addEntry()
andMenuAdmin::removeEntry()
have been removed. UsePiwik\Plugin\Menu
instead. - The deprecated methods
MenuTop::addEntry()
andMenuTop::removeEntry()
have been removed. UsePiwik\Plugin\Menu
instead. - The deprecated method
SettingsPiwik::rewriteTmpPathWithInstanceId()
has been removed. - The following deprecated methods from the
Piwik\IP
class have been removed, usePiwik\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.- Update classes should not declare static
getSql()
andupdate()
methods anymore. It is still supported to use those, but developers should instead override theUpdates::getMigrationQueries()
andUpdates::doUpdate()
instance methods.
API
classes can now use dependency injection in their constructor to inject other instances.
- There is now a command
core:purge-old-archive-data
that can be used to manually purge temporary, error-ed and invalidated archives from one or more archive tables. - There is now a command
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.
- The event
User.getLanguage
has been removed. - The following deprecated event has been removed:
TaskScheduler.getScheduledTasks
- Special handling for operating system
Windows
has been removed. Like other operating systems all versions will now only be reported asWindows
with versions likeXP
,7
,8
, etc. - Reporting for operating systems has been adjusted to report information according to browser information. Visitor details now contain:
operatingSystemName
,operatingSystemIcon
,operatingSystemCode
andoperatingSystemVersion
- The following methods have been deprecated in favor of the new
Piwik\Intl
component:Piwik\Common::getContinentsList()
: useRegionDataProvider::getContinentList()
insteadPiwik\Common::getCountriesList()
: useRegionDataProvider::getCountryList()
insteadPiwik\Common::getLanguagesList()
: useLanguageDataProvider::getLanguageList()
insteadPiwik\Common::getLanguageToCountryList()
: useLanguageDataProvider::getLanguageToCountryList()
insteadPiwik\Metrics\Formatter::getCurrencyList()
: useCurrencyDataProvider::getCurrencyList()
instead
- The
Piwik\Translate
class has been deprecated in favor ofPiwik\Translation\Translator
. - The
core:plugin
console has been deprecated in favor of the newplugin:list
,plugin:activate
andplugin:deactivate
commands - The following classes have been deprecated:
Piwik\TaskScheduler
: usePiwik\Scheduler\Scheduler
insteadPiwik\ScheduledTask
: usePiwik\Scheduler\Task
instead
- The API method
UserSettings.getLanguage
is deprecated and will be removed from May 1st 2015. UseUserLanguage.getLanguage
instead - The API method
UserSettings.getLanguageCode
is deprecated and will be removed from May 1st 2015. UseUserLanguage.getLanguageCode
instead - The
Piwik\Registry
class has been deprecated in favor of using the container:Registry::get('auth')
should be replaced withStaticContainer::get('Piwik\Auth')
Registry::set('auth', $auth)
should be replaced withStaticContainer::getContainer()->set('Piwik\Auth', $auth)
- You can now generate UI / screenshot tests using the command
generate:test
- During UI tests we do now add a CSS class to the HTML element called
uiTest
. This allows you do hide content when screenshots are captured.
- A new command (core:fix-duplicate-log-actions) has been added which can be used to remove duplicate actions and correct references to them in other tables. Duplicates were caused by this bug: #6436
- Updated AngularJS from 1.2.26 to 1.2.28
- Updated piwik/device-detector from 2.8 to 3.0
- UI specs were moved from
tests/PHPUnit/UI
totests/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. - There is a new command
development:sync-system-test-processed
for core developers that allows you to copy processed test results from travis to your local dev environment.
- API responses containing visitor information will no longer contain the fields
screenType
andscreenTypeIcon
as those reports have been completely removed - os, browser and browser plugin icons are now located in the DevicesDetection and DevicePlugins plugin. If you are not using the Reporting or Metadata API to get the icon locations please update your paths.
- The deprecated method
Piwik\SettingsPiwik::rewriteTmpPathWithHostname()
has been removed. - The following events have been removed:
Log.formatFileMessage
Log.formatDatabaseMessage
Log.formatScreenMessage
- These events have been removed as Piwik now uses the Monolog logging library. Learn more.
- The event
Log.getAvailableWriters
has been removed: to add custom log backends, you now need to configure Monolog handlers - The INI options
log_only_when_cli
andlog_only_when_debug_parameter
have been removed
- We added the
symfony/var-dumper
library allowing you to better print any arbitrary PHP variable viadump($var1, $var2, ...)
. - Piwik now uses Monolog as a logger.
- The tracker proxy (previously in
misc/proxy-hide-piwik-url/
) has been moved to a separate repository: https://github.com/matomo-org/tracker-proxy.
- Some duplicate reports from UserSettings plugin have been removed. Widget URLs for those reports will still work till May 1st 2015. Please update those to the new reports of DevicesDetection plugin.
- The API method
UserSettings.getBrowserVersion
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getBrowserVersions
instead - The API method
UserSettings.getBrowser
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getBrowsers
instead - The API method
UserSettings.getOSFamily
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getOsFamilies
instead - The API method
UserSettings.getOS
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getOsVersions
instead - The API method
UserSettings.getMobileVsDesktop
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getType
instead - The API method
UserSettings.getBrowserType
is deprecated and will be removed from May 1st 2015. UseDevicesDetection.getBrowserEngines
instead - The API method
UserSettings.getResolution
is deprecated and will be removed from May 1st 2015. UseResolution.getResolution
instead - The API method
UserSettings.getConfiguration
is deprecated and will be removed from May 1st 2015. UseResolution.getConfiguration
instead - The API method
UserSettings.getPlugin
is deprecated and will be removed from May 1st 2015. UseDevicePlugins.getPlugin
instead - The API method
UserSettings.getWideScreen
has been removed. UseUserSettings.getScreenType
instead. Piwik\SettingsPiwik::rewriteTmpPathWithInstanceId()
has been deprecated. Instead of hardcoding thetmp/
path everywhere in the codebase and then callingrewriteTmpPathWithInstanceId()
, developers should get thepath.tmp
configuration value from the DI container (e.g.StaticContainer::getContainer()->get('path.tmp')
).- The method
Piwik\Log::setLogLevel()
has been deprecated - The method
Piwik\Log::getLogLevel()
has been deprecated
- The HTTP Tracker API does now respond with a HTTP 400 instead of a HTTP 500 in case an invalid
idsite
is used
- New URL parameter
send_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.
- Development related console commands are only available if the development mode is enabled. To enable the development mode execute
./console development:enable
. - The command
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.
- Most methods of
Piwik\IP
have been deprecated in favor of the new piwik/network component. - The file
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 inconfig/global.ini.php
- Code for manipulating IP addresses has been moved to a separate standalone component: piwik/network. Backward compatibility is kept in Piwik core.
- Updated AngularJS from 1.2.25 to 1.2.26
- Updated jQuery from 1.11.0 to 1.11.1
- The Auth interface has been modified, existing Auth implementations will have to be modified. Changes include:
- The initSession method has been moved. Since this behavior must be executed for every Auth implementation, it has been put into a new class: SessionInitializer. If your Auth implementation implements its own session logic you will have to extend and override SessionInitializer.
- The following methods have been added: setPassword, setPasswordHash, getTokenAuthSecret and getLogin.
- Clarifying semantics of each method and what they must support and can support.
- Read the documentation for the Auth interface to learn more.
- The
Piwik\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.- The
Piwik\Unzip\*
classes (Tar, PclZip, Gzip, ZipArchive) have moved to thePiwik\Decompress\*
namespace (inside the new repository). Piwik\Unzip\UncompressInterface
has been moved and renamed toPiwik\Decompress\DecompressInterface
(inside the new repository).
- The
Piwik::setUserHasSuperUserAccess
method is deprecated, instead use Access::doAsSuperUser. This method will ensure that super user access is properly rescinded after the callback finishes. - The class
\IntegrationTestCase
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\TestCase\SystemTestCase
instead. - The class
\DatabaseTestCase
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\TestCase\IntegrationTestCase
instead. - The class
\BenchmarkTestCase
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\TestCase\BenchmarkTestCase
instead. - The class
\ConsoleCommandTestCase
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\TestCase\ConsoleCommandTestCase
instead. - The class
\FakeAccess
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\Mock\FakeAccess
instead. - The class
\Piwik\Tests\Fixture
is deprecated and will be removed from February 6th 2015. Use\Piwik\Tests\Framework\Fixture
instead. - The class
\Piwik\Tests\OverrideLogin
is deprecated and will be removed from February 6ths 2015. Use\Piwik\Framework\Framework\OverrideLogin
instead.
- The pivotBy and related query parameters can be used to pivot reports by another dimension. Read more about the new query parameters here.
- Updated AngularJS from 1.2.13 to 1.2.25
generate:angular-directive
lets you easily generate a template for a new angular directive for any plugin.
- Piwik 2.8.0 now requires PHP >= 5.3.3.
- If you use an older PHP version, please upgrade now to the latest PHP so you can enjoy improvements and security fixes in Piwik.
- Several APIs will now expose a new metric
nb_users
which measures the number of unique users when a User ID is set. - New APIs have been added for Content Tracking feature: Contents.getContentNames, Contents.getContentPieces
- The
Piwik\Menu\MenuAbstract::add()
method is deprecated in favor ofaddItem()
. Read more about this here: #6140. We do not plan to remove the deprecated method before Piwik 3.0.
- It is now easier to generate the URL for a menu item see #6140, urlForDefaultAction(), urlForAction(), urlForModuleAction()
core:clear-caches
Lets you easily delete all caches. This command can be useful for instance after updating Piwik files manually.
- The
'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:- A bug in JSON formatting was fixed so API methods that return simple associative arrays like
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.
- A bug in JSON formatting was fixed so API methods that return simple associative arrays like
- If an API returns an indexed array, it is now possible to use
filter_limit
andfilter_offset
. This was before only possible if an API returned a DataTable. - The Live API now returns only visitor information of activated plugins. So if for instance the Referrers plugin is deactivated a visitor won't contain any referrers related properties. This is a bugfix as the API was crashing before if some core plugins were deactivated. Affected methods are for instance
getLastVisitDetails
orgetVisitorProfile
. 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.
- We removed our own autoloader that was used to load Piwik files in favor of the composer autoloader which we already have been using for some libraries. This means the file
core/Loader.php
will no longer exist. In case you are using Piwik from Git make sure to runphp composer.phar self-update && php composer.phar install
to make your Piwik work again. Also make sure to no longer includecore/Loader.php
in case it is used in any custom script. - We do no longer store the list of plugins that are used during tracking in the config file. They are dynamically detect instead. The detection of a tracker plugin works the same as before. A plugin has to either listen to any
Tracker.*
orRequest.initAuthenticationObject
event or it has to define dimensions in order to be detected as a tracker plugin.
- Javascript Tracking API: if you are using
getCustomVariable
function to access custom variables values that were set on previous page views, you now must also callstoreCustomVariablesInCookie
before the first call totrackPageView
. Read more about Javascript Tracking here. - The settings API will receive the actual entered value and will no longer convert characters like
&
to&
. If you still want this behavior - for instance to prevent XSS - you can define a filter by setting thetransform
property like this:$setting->transform = function ($value) { return Common::sanitizeInputValue($value); }
- Config setting
disable_merged_assets
moved fromDebug
section toDevelopment
. 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 instanceVisitsSummary.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 #5987
The 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 aVisualizations
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.
- Report to add a new report
- Action Dimension to add a dimension that tracks action related information
- Visit Dimension to add a dimension that tracks visit related information
- Conversion Dimension to add a dimension that tracks conversion related information
- Dimension to add a basic non tracking dimension that can be used in
Reports
- Widgets to add or modify widgets
- These Menu classes got new methods that make it easier to add new items to a specific section
- MenuAdmin to add or modify admin menu items.
- MenuReporting to add or modify reporting menu items
- MenuUser to add or modify user menu items
- Tasks to add scheduled tasks
generate: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 mode
Find the general Matomo Changelogs for each release at matomo.org/changelog