# Matomo Platform Changelog

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](https://matomo.org/changelog)** lets you see more details about any Matomo release, such as the list of new guides and FAQs, security fixes, and links to all closed issues.

## Matomo 6.0.0

### Breaking Changes
* API method parameters are now validated against their declared type. A parameter supplied with a value its declared type cannot accept, for example an array where a string is expected, is rejected with a bad request error. For a parameter declared with a `null` default this replaces the previous silent fallback to `null`; for a parameter declared without a default the error message changes from `General_PleaseSpecifyValue` to `General_InvalidValueForParameter`. Parameters declared with any other default still fall back to it. A parameter that is not supplied continues to use its default, as does one supplied without a value (`&param=`) — except `string` parameters, which receive `''` as they always have. This applies to API classes that set `$autoSanitizeInputParams = false` or methods annotated `@unsanitized`; every other API method resolves its parameters through the sanitizing path and is unaffected.
* Before upgrading a proxied installation that configures `[General] proxy_host_headers`, add both the public hostname and the hostname used to reach Matomo to `trusted_hosts`; otherwise the invalid-host warning replaces the login form. With trusted-host checking enabled, `Piwik\Url::isValidHost()` without an explicit hostname now validates the proxy-derived hostname, and `Piwik\Url::getCurrentHost()` returns that hostname only when it is accepted, falling back to the request/configuration-derived hostname otherwise. New installations record both hostnames automatically.
* The deprecated method `Piwik\Archive::getBlob()` has been removed. Use one of the `Piwik\Archive::getDataTable*()` methods instead.
* The deprecated method `Piwik\Archive::clearStaticCache()` has been removed. It was a no-op kept only for backwards compatibility.
* The deprecated method `Piwik\ArchiveProcessor\Parameters::setIsPartialArchive()` has been removed. Use `Piwik\ArchiveProcessor\Parameters::setArchiveOnlyReport()` instead.
* The deprecated method `Piwik\Db\Adapter::getDefaultPortForAdapter()` has been removed. Use `Piwik\Db\Schema::getDefaultPortForSchema()` instead.
* The deprecated method `Piwik\Url::saveCORSHostnameInConfig()` has been removed. It was no longer in use.
* The deprecated method `Piwik\Plugin\Report::getThirdLeveltableDimension()` has been removed. Use `Piwik\Plugin\Report::getNthLevelTableDimension(2)` instead.
* The deprecated `API.getSettings` API method has been removed, along with the default `[APISettings]` section shipped in `config/global.ini.php` that it exposed. There is no replacement; integrations that fetched key/value pairs from that section over the REST API must migrate to another mechanism. Any `[APISettings]` entries in a local `config.ini.php` simply become inert.
* The deprecated static method `getDefaultPort()` has been removed from `Piwik\Db\AdapterInterface` and its implementations (`Piwik\Db\Adapter\Mysqli`, `Piwik\Db\Adapter\Pdo\Mysql`). Use `Piwik\Db\Schema::getDefaultPortForSchema()` instead.
* The deprecated method `Piwik\Plugins\Overlay\API::getExcludedQueryParameters()` has been removed. Use the `SitesManager.getExcludedQueryParameters` API method instead.
* The deprecated method `Piwik\Db::optimizeTables()` has been removed. Use `Piwik\Db\Schema::getInstance()->optimizeTables()` instead.
* The deprecated method `Piwik\Db::isOptimizeInnoDBSupported()` has been removed. Use `Piwik\Db\Schema::getInstance()->isOptimizeInnoDBSupported()` instead.
* The deprecated method `Piwik\Db\TransactionLevel::setUncommitted()` has been removed. Use `Piwik\Db\TransactionLevel::setTransactionLevelForNonLockingReads()` instead.
* The deprecated `SitesManager.setGlobalExcludedQueryParameters` API method has been removed. Use `SitesManager.setGlobalQueryParamExclusion` instead.
* The deprecated method `Piwik\API\Request::isTokenAuthProvidedSecurely()` has been removed.
* The API methods `Annotations.add`, `Annotations.save` and `Annotations.delete` now require `Write` permission. Previously `Annotations.add` required only `View` permission, and the author of an annotation could modify or delete it with only `View` permission.
* Following the upgrade to psr/log 3, `Piwik\Log\LoggerInterface` (which extends `Psr\Log\LoggerInterface`) now requires the PSR-3 `void` return type on its logging methods (`log()`, `debug()`, `info()`, `notice()`,
  `warning()`, `error()`, `critical()`, `alert()`, `emergency()`). Plugins that implement this interface directly must add the `: void` return type to these methods. Plugins that obtain the logger through
  dependency injection or extend `Piwik\Log\Logger` are not affected.
* The deprecated archiving script `./misc/cron/archive.sh` has been removed. Use the console command `core:archive` instead.
* The `SEO` plugin has been removed, along with its `SEO` widget and the `SEO.getRank` API method.
* The `TrackingSpamPrevention` plugin is now bundled with core and activated by default. It is no longer distributed on the Marketplace and can no longer be uninstalled, and updating to Matomo 6 activates it on installations where it was deactivated or was never installed. `Piwik\Plugin\Manager::isPluginBundledWithCore('TrackingSpamPrevention')` therefore returns `true` from now on.
* The `TrackingSpamPrevention` setting `block_clouds` no longer controls GeoIP organisation blocking. It now only enables the daily cloud provider IP range sync, and is relabelled accordingly. A new `cloud_blocking_mode` setting decides whether organisation names are matched against nothing (`off`), Matomo's maintained default list (`default`), or the `organisation_block_list` setting (`custom`). Both are `[TrackingSpamPrevention]` `config.ini.php` keys as well as UI settings, and `Piwik\Plugins\TrackingSpamPrevention\SystemSettings::getBlockedOrganisations()` now returns the list the selected mode puts into effect rather than the stored list. Installations that already had the plugin are migrated to the state they were already in, and keep the blocking they had until the database update runs, so nothing changes between the new files being deployed and `core:update`. An installation where this plugin was installed but deactivated needs the update run twice, because Matomo 6 activates the plugin during the first pass and only picks up its update in the next one. Installations treated as new, which includes Matomo 5 installations where this plugin was never installed, start with both options enabled.
* One Click Update now always downloads the update archive over HTTPS. The insecure "retry over HTTP" fallback screen and the `https` request parameter of the `CoreUpdater.oneClickUpdate` action have been removed, and the `$https` parameter of `Piwik\Plugins\CoreUpdater\Updater::updatePiwik()` and `Piwik\Plugins\CoreUpdater\Updater::getArchiveUrl()` has been removed. HTTP is only used when the `force_matomo_http_request` config option is enabled.
* The global function `_glob()` has been removed. Use the native `glob()` instead. As a consequence `glob()` must no longer be listed in the `disable_functions` php.ini directive: Matomo now refuses to start with an explicit error message instead of emulating it. `glob()`, `fnmatch()` and `file_get_contents()` have also moved from the recommended to the required functions in the system check, which additionally catches a Suhosin function blacklist.
* The global functions `safe_serialize()` and `_safe_serialize()` have been removed. Use the native `serialize()` instead. Note that the retained `safe_unserialize()` accepts only a strict subset of PHP's serialization format, so native `serialize()` is a drop-in replacement only for values that contain no objects, no references and no resources. A reference produces an `R:` token, which `safe_unserialize()` rejects; a resource is serialized as `i:0;`, which it silently reads back as the integer `0` where `safe_serialize()` used to refuse to serialize it at all.
* The global function `_parse_ini_file()` has been removed. It was unused; use `Piwik\Config` for Matomo's configuration or `Matomo\Ini\IniReader` for other INI files.
* The global functions `safe_unserialize()` and `_safe_unserialize()` in `libs/upgradephp/upgrade.php` are kept. Note that these are a different, stricter implementation than `Piwik\Common::safe_unserialize()`, which wraps the native `unserialize()` with `allowed_classes => false` and applies none of the `MAX_SERIALIZED_*` input limits.
* The conditional fallback definitions for `mysqli_set_charset()`, `file_get_contents()`, `utf8_encode()`, `utf8_decode()`, `fnmatch()`, the `Error` class and the `PHP_INT_SIZE`/`PHP_INT_MAX` constants have been removed from `libs/upgradephp/upgrade.php`. All of these are provided natively by every supported PHP version; the fallbacks only ever activated on PHP versions that are no longer supported, or when the function had been turned off via `disable_functions`.
* The `gzopen()` fallback has also been removed from `libs/upgradephp/upgrade.php`. It aliased `gzopen()` to `gzopen64()` on distribution builds where zlib exposes only the latter, which is a packaging issue rather than a PHP version or `disable_functions` one. On such a build `Piwik\Unzip` now falls back to `PclZip`.
* Several core controller actions that return JSON now declare a native `string` return type as part of adopting the new `#[Piwik\Http\JsonResponse]` attribute. A plugin that extends one of these controllers and overrides such an action must declare a compatible `string` return type and re-declare `#[Piwik\Http\JsonResponse]` (attributes are not inherited).
* The deprecated Piwik-era color aliases `@color-black-piwik`, `@color-blue-piwik`, `@color-red-piwik` and `@color-green-piwik` have been removed from `plugins/Morpheus/stylesheets/base/colors.less`. Use `@color-black-matomo`, `@color-blue-matomo`, `@color-red-matomo` and `@color-green-matomo` instead.
* The third-party brand color variables `@color-orange-brand` (`#f57c00`), `@color-green-brandSocial` (`#009874`), `@color-blue-brandSocial` (`#3b5998`), `@color-blue-brandSocialLight` (`#1c87bd`) and `@color-blue-brandSocialVeryLight` (`#00aced`) have been removed. They described other companies' brands rather than Matomo's own palette; a plugin that still needs one of these colors should use the literal value.
* The never-referenced palette tokens `@color-gray-light` (`#f0f0f0`), `@color-gray-bright` (`#EBF2EB`), `@color-gray-400` (`#BCBCBC`), `@color-jetstream` (`#c3d9c4`), `@color-silver-l14`, `@color-silver-l50`, `@color-silver-l70` and `@color-silver-l98` have been removed. Use one of the remaining `@color-silver-*` variables, a `@theme-color-*` variable or a literal value instead.
* The stylesheet `plugins/Morpheus/stylesheets/base/mode-colors.less` has been removed together with the variables it defined, `@color-mode-black` and `@color-mode-white`. Use the `.inDarkMode()` mixin (still available from `plugins/Morpheus/stylesheets/base/mixins.less`) or the relevant `@theme-color-*` variable instead.
* The stylesheet `plugins/Login/stylesheets/variables.less` has been removed together with the variable it defined, `@login-section-background`. A plugin that registers this file in `getStylesheetFiles()` must drop that line, otherwise stylesheet merging fails with `The ui asset with 'href' = .../plugins/Login/stylesheets/variables.less is not readable`.
* The deprecated jQuery UI widget `$.fn.liveWidget` (`piwik.liveWidget`) has been removed together with the file `plugins/Live/javascripts/live.js` that defined it. Use the `Live.AutoRefreshWidget` Vue component instead.
* Less variables that were only used within a single stylesheet have been inlined or renamed to private `@_`-prefixed names, and are therefore no longer visible to other stylesheets: `@top-menu-nav-color` (`plugins/CoreHome/stylesheets/layout.less`), `@color-period-selector`, `@color-period-selector-input-radio`, `@color-period-selector-options-hover-background`, `@color-period-selector-calendar-hover-background` (`PeriodSelector.less`), `@add-widget-padding`, `@add-widget-border`, `@add-widget-space-or-radius`, `@add-widget-categories`, `@add-widget-widgets`, `@add-widget-preview`, `@add-widget-height`, `@add-widget-item-height` (`AddWidgetModal.less`) and `@calendarHeaderBackground`, `@calendarHeaderColor`, `@calendarCurrentStateHover`, `@calendarBorder` (`plugins/Morpheus/stylesheets/ui/_components.less`). These were never theme variables; use the `@theme-color-*` variable they were derived from instead.
* `CoreHome.EnrichedHeadline` no longer derives a report's inline help from the DOM. It used to look for a `.reportDocumentation[data-content]` element inside the next sibling of its headline and show that text behind a help icon; the text now comes from its `inline-help` attribute. The `piwik:reportChanged` DOM event, which told a headline to re-read that element, has been removed with it. Headlines rendered by `Piwik\View::singleReport()`, or by a template reproducing its shape, therefore lose their help icon unless `inline-help` is passed explicitly.
* The development-only console commands `git:commit`, `git:pull` and `git:push` have been removed. They were thin wrappers around `git` that predate the current submodule workflow; use `git` directly instead.
* Flat-first Actions archiving is enabled by default for new installations, as
  `datatable_archiving_maximum_rows_actions_flat` now defaults to `10000` instead of `0`. Installations
  updated from Matomo 5 keep the legacy hierarchical-only archiving, as the update writes a `0` to their
  `config.ini.php`, unless the setting is already configured there or in `common.config.ini.php`. While it
  is enabled, the page URL and page title reports (including their entry and exit variants) are capped by
  this setting instead of `datatable_archiving_maximum_rows_actions` and
  `datatable_archiving_maximum_rows_subtable_actions`, each of them is stored as one additional archive
  record, and their page categories are no longer truncated per category, so a category no longer ends in
  a summary row of its own.
* Request parameters are no longer trimmed while a request is parsed. `Piwik\API\Request::getRequestArrayFromString()` used to apply `trim((string) $value)` to every non-array parameter, so leading and trailing whitespace in values such as a `label` or a segment operand is now preserved, and scalars keep their type. As a consequence a boolean passed through `Piwik\API\Request::processRequest()` no longer arrives as `'1'`/`''`: a parameter read with `Piwik\Common::getRequestVar($name, $default, 'string')` or `Piwik\Request::getStringParameter()` falls back to its default instead. Pass a string, or read it with `Piwik\Request::getBoolParameter()`, which accepts real booleans.
* The `SitesManager.getImageTrackingCode` API method now requires view access to the given site, matching `SitesManager.getJavascriptTag`. Its parameters are typed as well, so `idSite` must be an integer and `forceMatomoEndpoint` a boolean — the latter is now read with `Piwik\Request::getBoolParameter()`, which understands `0`, `1`, `true` and `false` and silently falls back to `false` for anything else, where previously any truthy value enabled it.
* The legacy Transitions renderer has been removed together with the JavaScript globals it defined, `Piwik_Transitions`, `Piwik_Transitions_Canvas` and `Piwik_Transitions_Util`. Use the `Transitions.TransitionsReport` Vue component instead, or `DataTable_RowActions_Transitions.launchForUrl()`, which is unchanged and still opens the report for a URL. `Piwik_Transitions_Model` and `Piwik_Transitions_Ajax` remain, without the renderer-only members `htmlLoaded()`, `getShareInGroupTooltip()` and `callTransitionsController()`. The controller action `index.php?module=Transitions&action=renderPopover`, which rendered the removed markup, and the `@internal` API method `Transitions.getTranslations`, which only supplied its labels, have been removed with it, along with the `Piwik_Transitions_Translations` global that template defined. `Piwik_Transitions_Ajax.callApi()` no longer falls back to `Piwik_Popover.showError()` when no `setErrorCallback()` was registered: an API error is dropped and the request's callback never runs, so a caller that wants errors surfaced must register one.
* A plugin with no cover image of its own now falls back to the same generic `uncategorised` cover as every other plugin. `Piwik\Plugins\Marketplace\Plugins::addPluginCoverImage()` used to give a paid plugin owned by `piwik` or `matomo-org` the Matomo-branded `matomo.png` cover instead, which the redesigned cards mark with a Matomo chip rather than a whole cover image. The Marketplace's own category stand-ins now count as no cover image as well, so a plugin the Marketplace categorised also takes the generic fallback.
* Several parameters of the `Goals` API methods now declare a native `bool` type: `caseSensitive`, `allowMultipleConversionsPerVisit` and `useEventValueAsRevenue` of `Goals.addGoal` and `Goals.updateGoal`, `abandonedCarts` of `Goals.getItemsSku`, `Goals.getItemsName` and `Goals.getItemsCategory`, and `showAllGoalSpecificMetrics` and `compare` of `Goals.get` and `Goals.getMetrics`. Over HTTP these parameters were previously passed through as raw strings, so any value other than `0` was truthy: `&abandonedCarts=false` returned abandoned carts rather than purchased products. They are now read like every other boolean parameter, which accepts `0`, `1`, `false` and `true` and falls back to the default for anything else. Plugins calling these methods directly in PHP must pass a boolean or a value PHP can coerce to one; `null` is no longer accepted.
* The `idGoal` parameter of `Goals.deleteGoal` and `Goals.updateGoal` now declares a native `int` type, like `Goals.getGoal` already did. A value that is not a number, such as `idGoal=ecommerceOrder`, is rejected by the API layer instead of being coerced to `0`. Plugins calling these methods directly in PHP must pass an integer or a numeric string.
* The Marketplace's `PluginList` Vue component has been removed along with the plugin list it rendered. The redesigned page is built from the `PluginGrid`, `PluginSection`, `PluginCard`, `CategoryTabs`, `MarketplaceHero` and `SortMenu` components the plugin now exports instead. The translation keys `Marketplace_CreatedBy`, `Marketplace_Intro`, `Marketplace_IntroSuperUser`, `Marketplace_NoThemesFound`, `Marketplace_PriceFromPerPeriod`, `Marketplace_Show`, `Marketplace_Sort` and `Marketplace_SortByPopular` have been removed with the markup that used them. The `pluginType` hash parameter is no longer written and only `themes` and `plugins` are still read back, for the links CorePluginsAdmin makes; `#?pluginType=premium` no longer opens a filtered list and is silently ignored, landing the reader on the full catalogue instead.
* The site selector dropdown (`CoreHome.SiteSelector`) now uses the generic dropdown panel and search input markup, so the classes it used to expose have been removed: `custom_select_search`, `custom_select_container`, `custom_select_ul_list`, `custom_select_all`, `websiteSearch`, `inp`, `reset`, `noresult`, `autocompleteMatched`, and the `dropdown` class on the panel itself. Code that selected inside the site selector must target `.piwikSelector__dropdown` for the panel, `.mtm-dropdownPanel__menu` for the site list, `.mtm-dropdownPanel__menuItem` / `.mtm-dropdownPanel__menuLink` / `.mtm-dropdownPanel__menuLabel` for an entry, `.mtm-dropdownPanel__noResult` for the empty state, `.mtm-dropdownPanel__searchMatch` for the highlighted search term, and `.mtm-searchInput__input` / `.mtm-searchInput__clear` for the search field. The unused Less rules that styled `custom_select_search` inside `.segment-element` have been removed from `plugins/SegmentEditor/stylesheets/segmentation.less` and `plugins/Morpheus/stylesheets/ui/_components.less`. `plugins/CoreHome/vue/src/SiteSelector/SiteSelector.less` also drops the now unmatched global rules `.sites_selector_container`, `.custom_select_block_show`, `.custom_selector_container .ui-menu-item`, `.siteSelect a` and `.custom_select_main_link`; nothing in core or the bundled plugins carried that markup, but a third-party plugin reproducing it would lose the styling. The internal `AllSitesLink.vue` component has been removed: it was never exported from `CoreHome`, and its "All Websites" row is now rendered by `SiteSelector.vue` as a regular panel menu item.
* The deprecated `$webSearchEnabled` parameter of the `Piwik\Plugins\AIProviders\AIProviderResponse` constructor has been removed. Pass a `Piwik\Plugins\AIProviders\WebSearchUsage` instead, which reports the searches, queries and citations a completion actually produced rather than a bare flag. It occupied position 8, so a caller that passes the execution time and stop reason positionally must drop the flag or those values now bind to the wrong parameters; the execution time, stop reason and `WebSearchUsage` each move up one position, so `WebSearchUsage` is now 10th rather than the 11th it held in Matomo 5.14.0.
* The deprecated method `Piwik\Plugins\AIProviders\AIProviderResponse::isWebSearchEnabled()` has been removed, along with the `webSearchEnabled` key of `AIProviderResponse::toArray()`. Use `wasWebSearchUsed()` and the `webSearchUsed` key instead, which say what they mean; `Piwik\Plugins\AIProviders\AIRequest::isWebSearchEnabled()` is unaffected and keeps reporting what the request asked for.
* The deprecated method `Piwik\Plugins\AIProviders\Provider\AIProvider::isWebSearchUsed()` has been removed and is no longer consulted. A provider that reported a search by overriding it must now override `supportsWebSearch()` to declare the capability and pass a `WebSearchUsage` to `buildResponse()`; an override left in place is simply ignored, so such a provider's answers report no search until it migrates.
* Custom Dimension reports now credit a goal conversion to the value its visit ended with when the conversion recorded no value of its own, which happens when a visit-scoped dimension is only sent after the goal converted. Those conversions were previously left out of the report altogether, so `CustomDimensions.getCustomDimension` can return higher conversion counts for affected dates once they are re-archived. A conversion that did record a value is unaffected and still counts under that value. A visit that later sent the dimension as an empty value now credits its earlier conversions to "Value not defined". Segmented reports get the same credit, and a conversion is still counted once when the segment matches several actions of its visit.

### New Features
* Added contextual recommendations for Premium products based on how Matomo is being used.

### New APIs
* The new `Template.beforeDashboardWidgets` event is posted at the top of the dashboard, above the widgets, and allows a plugin to render its own content there. It is posted by `plugins/Dashboard/templates/embeddedIndex.twig`; like the other `Template.*` events, a listener takes the rendered output by reference (`function (&$out)`) and appends its markup to it.
* The new `DragHandle` Vue component in CoreHome renders the standard 6-dot drag-handle icon, for use inside `DraggableList` rows. The `DraggableList` component's `handle` option now also works with real browser drags, which retarget `dragstart` to the draggable element (previously the handle was only recognised in synthetically dispatched events).
* The new `closeTooltips()` helper in CoreHome closes the jQuery UI tooltips bound to a selector's elements, including pending delayed shows — for cases where no mouse event will fire that would close them, eg. once an HTML5 drag has started.
* The generic dropdown panel (`plugins/Morpheus/stylesheets/ui/_dropdown-panel.less`) gained the elements `.mtm-dropdownPanel__search` (a nest element that hosts a search input inside a panel), `.mtm-dropdownPanel__searchMatch` (the part of a menu label matching the typed term) and `.mtm-dropdownPanel__noResult` (the row shown when a search yields nothing), plus the modifiers `.mtm-dropdownPanel__menu--scrollable` (caps the menu at `calc(80vh - 60px)` and scrolls) and `.mtm-dropdownPanel__menu--gutter` (an 8px horizontal gutter so the rows line up with a search input above them). The panel itself is now a fixed 254px wide rather than a 240px minimum. `.mtm-dropdownPanel__menuLabel` now truncates with an ellipsis instead of only allowing it.
* The `SearchInput` clear button exported from `CoreHome` now carries a translated `title` (`General_Clear`), giving it an accessible name.
* A new `#[Piwik\Http\JsonResponse]` attribute can be applied to a plugin controller action to declare that it returns a JSON response. When present, Matomo (re-)sends the `Content-Type: application/json` header after the action has returned, so it can no longer be overwritten by output produced while the action builds its response (for example a rendered `Piwik\View`, which sends `text/html`). An action using the attribute must return the JSON string, must not send the header itself, and must not emit output (`echo`/`print`/`flush`) or call `exit`/`die` before returning — otherwise the response headers are committed first and the JSON `Content-Type` cannot be applied. The attribute is not inherited: a subclass overriding a JSON action must re-declare it. These requirements are enforced by PHPStan rules.
* The `PasswordConfirmation` component exported from `CorePluginsAdmin` gained a `requireDeleteConfirmation` prop, off by default. When it is set the confirmation dialog additionally asks the user to type `delete` - an untranslated literal, the same word in every language - and its Confirm button stays disabled until that matches exactly and, where re-authentication applies, a password has been entered. It is meant for actions that permanently remove data, and is used in four places in PrivacyManager: the settings for regularly deleting old raw data, for deleting old aggregated report data and for enforcing a raw data retention period through a compliance policy - the last of these only when the save being confirmed actually switches retention on - and the Purge DB Now link, which deletes straight away rather than scheduling a deletion for later. A plugin that supplies an alternative identity confirmation component through the `PasswordConfirmation.altIdComponent` event keeps that component on screen while the word is missing, greyed out and made inert inside a wrapper the dialog owns, so it can be neither clicked nor reached by keyboard until the word matches, and pressing Enter in the dialog activates that component rather than confirming without it. The component has to contain a single `<a>` or `<button>` carrying the `btn` class for either to reach it.
* The `SearchInput` component exported from `CoreHome` gained a `focused` prop and a `blur()` method: setting `focused` to `true` moves focus to the inner input and calling `blur()` on the component removes it, both of which were previously impossible because binding `v-focus-if` or an element ref to the component targeted its non-focusable wrapper. `CoreHome.QuickAccess` now renders this component instead of duplicating its markup, so its search field is no longer a separate `input` that happens to carry the same classes. Quick search also runs off the field's value rather than off keystrokes, so text that arrives without one (a pasted term, an IME candidate committed with the mouse) now searches too, and keys that belong to an open IME candidate window no longer act on the result list.
* `Piwik\Plugin\ThemeStyles` gained `$colorWarning`, `$colorDanger`, `$colorTextBrand`, `$colorBackgroundBrandTinyContrast`, `$colorBackgroundBrandLowContrast` and `$colorBorderBrand`, exposed to Less as `@theme-color-warning`, `@theme-color-danger`, `@theme-color-text-brand`, `@theme-color-background-brand-tinyContrast`, `@theme-color-background-brand-lowContrast` and `@theme-color-border-brand`.
* A template extending `@Morpheus/admin.twig` can override the new `contentClass` block to put a class on the page's `#content` element. Core provides `admin--wide`, which widens the content area for admin pages that lay out in columns rather than in a single text measure.
* The new `PrivacyManager.compliancePolicySettingsUpdated` event announces the compliance policy settings a request has just changed, so an audit trail can record who changed what. It is posted by `PrivacyManager.setCompliancePolicySettings` and `PrivacyManager.enforceCompliancePolicySettings` once per call, and only when something actually changed: a request that fails, or that repeats the state a policy is already in, posts nothing. Its single array parameter holds the policy id, the `idSite` the policy was changed for (`null` for the instance wide state), whether every toggleable setting of the policy is enforced afterwards, and the settings whose enforcement state or compliance status changed. It deliberately carries no request parameters, and therefore no password confirmation or authentication token.

### HTTP API
* Report rows now include a percentage-of-report-total value for each metric the report processes totals for, as an additional
  `{metric}_percent_of_total` column (eg, `nb_visits_percent_of_total`). The values match the ratio percentages the report tables
  show on hover, follow `format_metrics` like other percent metrics, and are included in all export formats. Non-additive metrics
  (unique visitors and users) are excluded, as their report total is not a meaningful denominator. The columns can be disabled
  by setting the new `percent_of_total=0` request parameter (or `totals=0`). Note for CSV/TSV consumers parsing columns by
  position: the new columns change the header and column count, pass `percent_of_total=0` to keep the previous output.
  A report that already expresses a metric as a percentage of its own, through a `{metric}_percentage` column (eg,
  `DevicePlugins.getPlugin`, whose percentage leaves out the visits of browsers where plugins cannot be detected), does not
  get a `{metric}_percent_of_total` column for that metric, as the two percentages would contradict each other.
  `API.getProcessedReport` places each percentage directly after the metric it belongs to, and returns one only when that
  metric is itself a column of the report: a report with a total for bounces but no `Bounces` column no longer carries a
  `bounce_count_percent_of_total` entry in `columns`, `metricTypes`, `metricsDocumentation` or `reportData`.
* Scheduled reports now include the `{metric}_percent_of_total` columns, with the label depending on how much room the
  format has. CSV and TSV carry the full translated name (eg, `Visits (%)`) rather than the column id, while all other
  columns keep the id they had before. HTML email shortens it to `(%)`, since the column always sits directly to the right
  of the metric it belongs to. PDF leaves the columns out altogether: a portrait page has no room for a percentage after
  every metric without squeezing the table until values are truncated. The PDF says so in a note on its front page, and
  the report scheduling form says so under `Report Format`. A scheduled report has no request parameter of its own, so
  unlike an API consumer its owner cannot turn the columns off with `percent_of_total=0`. In CSV and TSV the header of a
  percentage column follows the report language while every other header keeps its untranslated id, so a consumer
  matching headers by name sees a different string per language.
* Custom report format renderers extending `Piwik\ReportRenderer` now receive the `{metric}_percent_of_total` columns as
  well. `ReportRenderer::translatePercentOfTotalColumns()`, `shortenPercentOfTotalColumnLabels()` and
  `removePercentOfTotalColumns()` are available to treat them the way the built-in formats do.
* A PDF report table now fills the page width exactly. Rounding each column up used to push wide tables past the page,
  clipping the last column of a report carrying ten or more metrics.

### Deprecations
* The component-oriented theme variable `@theme-color-widget-background` (`ThemeStyles::$colorWidgetBackground`)
  is deprecated and will be removed in Matomo 7; use `@theme-color-background-contrast` instead. It is the generic
  elevated content surface and is already used well beyond widgets.
* The component-oriented theme variables `@theme-color-menu-contrast-text`, `@theme-color-menu-contrast-textSelected`,
  `@theme-color-menu-contrast-textActive`, `@theme-color-menu-contrast-background`,
  `@theme-color-menu-contrast-backgroundHover`, `@theme-color-widget-border`, `@theme-color-widget-title-text`,
  `@theme-color-widget-title-background` and `@theme-color-widget-exported-background-base` (and the corresponding
  `ThemeStyles` properties, also readable via `themeStyles.getPropertyValue()`) are deprecated and will be removed
  in Matomo 7. Matomo's theming is moving from component-oriented variable names to usage-oriented ones; because
  these variables fill roles that no existing variable covers, usage-oriented replacements will be defined before
  they are removed. They keep working until then.

### Internal Changes
* `./console vue:build` no longer emits the unminified `plugins/<Plugin>/vue/dist/<Plugin>.umd.js` bundle. Only the
  minified `<Plugin>.umd.min.js` was ever loaded by Matomo, and development mode uses the `<Plugin>.development.umd.js`
  produced by `./console vue:build --watch`. Plugin authors can delete the committed `vue/dist/<Plugin>.umd.js` file
  from their repository and add `/vue/dist/*.umd.js` to their `.gitignore`. Nothing else needs to change; the file is
  simply no longer regenerated.
* Select form fields (`uicontrol="select"`) are now rendered as the bordered, rounded control used by the
  expandable selects and the top-level selectors, instead of Materialize's underlined field: a 38px box with a
  chevron, and a dropdown card that opens below the field. Plugin stylesheets that pin a narrow width on
  `.select-wrapper` may need widening, because the control now reserves horizontal padding for its text and
  chevron — too little width shows an ellipsised option label. Stylesheets that positioned Materialize's own
  `.caret`, or that tuned the inner `input`'s height, line-height or font-size for the underlined control, can
  drop those rules; the shared styles size the field. The field also reserves space above the control so that it
  sits on the same centre line as a plain text input beside it; stylesheets that nudged a select into line with
  its neighbours by hand can drop those rules too.
* A select inside a content table (the `v-content-table` directive, which adds the `entityTable` class) is
  rendered as a compact 32px control with no space reserved for a label, because the column heading names the
  field. Per-table rules that hand-rolled that compactness for the old underlined control can be dropped.
* While its dropdown is open, a select adds the `expanded` class to its `.select-wrapper` and turns its chevron,
  matching the highlighted border and the chevron behaviour of the other dropdowns; the expandable select and the
  site selector turn their chevrons too. Two changes affect plugin stylesheets: the select's chevron now sets its
  own `font-size` instead of inheriting the surrounding text size, and `.expandableSelector__chevron` uses
  `margin-right` rather than `padding-right`, so that the rotation turns the glyph in place.
* The expandable select (`uicontrol="expandable-select"`) now renders its option list as a direct child of
  `<body>` and positions it against the viewport, so that a scrolling or clipping ancestor — a modal, a panel —
  can no longer cut it off. The list is no longer a descendant of `.expandableSelector`, so plugin stylesheets
  and scripts that reached it that way (or through an enclosing `.modal`) no longer match. It carries the
  classes `expandableList expandableSelector__list` and a `data-name` attribute holding the field's name, which
  is the supported way to target a particular field's list. An element rendered at page level that belongs to a
  control inside a Materialize modal can set `data-matomo-modal-escapee` to that modal's
  `data-matomo-modal-id` to be exempted from its focus trap, which otherwise prevents it from holding focus. The
  exemption applies only to the modal named, so an element belonging to one modal cannot hold focus over another.
* **A report's actions have moved out of the icon bars above and below the data table into a single report header.**
  The header is rendered beside the table rather than inside it, so an action element is no longer a descendant of
  `.dataTable`. A handler bound on the table alone never sees it: bind on the report wrapper instead, or reuse
  `dataTable._findReportScope()`. Delegate rather than bind directly, because the header's menu is rendered by Vue after
  a plugin's `init()` runs, and namespace your handler so it survives the reloads that rebuild the table.
* **A `dataTable` subclass whose `init()` lists its handlers instead of calling the base `bindEventsAndApplyStyle()` must
  also call `self.syncReportHeaderActions(domElem)`.** Without it the shared header is never told what the report offers,
  and a dashboard widget - whose header is declared empty and filled from here - shows no actions at all.
* The classes and ids the old bars carried are gone with them: `.dataTableHeaderControls`, `.searchAction`,
  `.dataTableSearchInput`, `a.dropdownConfigureIcon`, `.activateVisualizationSelection`, `.periodName`, and the
  materialize `dropdown-content` wrappers. The action classes themselves are unchanged - `.dataTableAction`,
  `.activateExportSelection`, `.annotationView` and `.tableIcon[data-footer-icon-id]` still identify the same actions,
  now inside `.reportHeader__actionsMenu`.
* **The "rows to display" control is no longer a Materialize select.** `.limitSelection` now holds a
  `.mtm-selector` - a `button.mtm-selector__trigger` and a panel whose choices are `a[data-limit]`
  inside `.mtm-dropdownPanel__menu` - so `.select-wrapper`, `input.select-dropdown` and the native
  `<select>` are gone. Read the current value from the trigger's label and pick one by its
  `data-limit`. On a report with pagination the control now sits inside
  `.dataTablePaginationControl` rather than in a row of its own.
* The "export as image" icon no longer carries the id `dataTableFooterExportAsImageIcon`. It is now scoped to the
  placement it renders in, `dataTableExportAsImageIcon-header`. A page showing several image-exportable reports still
  repeats it, so prefer selecting `.dataTableAction.tableIcon` within the report you mean.
* A dashboard layout is now filtered against the widgets available to the user it is served to, so a
  widget that user may not use is dropped instead of being rendered and left to fail on its own API
  calls. This matters for a plugin that disables a widget for some users: `createNewDashboardForUser`,
  `resetDashboardLayout` and `copyDashboardToUser` build a layout from the *calling* user's widget list
  and store it for someone else, so such a widget could end up saved in a dashboard whose owner has no
  access to it. The filtering lives in
  `Piwik\Plugins\Dashboard\Dashboard::removeWidgetsNotAvailableToUser()`, which is `@internal`: it
  must not be called while the widget list is being built, so it is named here to locate the change
  rather than to be called from a plugin.

## Matomo 5.14.1

### New APIs
* `Piwik\Http::sendHttpRequest()` and `Piwik\Http::sendHttpRequestBy()` extended info (`$getExtendedInfo = true`)
  now includes an `effectiveUrl` entry: the final URL after following redirects. Best effort on the `fopen`
  transport, which follows redirects internally.

### New commands

* New command `marketplace:warm-cache` refetches the plugin and theme lists shown in the Marketplace overview. With `--if-older-than=<seconds>` it only refetches when the lists are missing or at least that old. Matomo runs it in the background to refresh the lists at spread-out times rather than on the hour, so it does not normally need to be run by hand.

## Matomo 5.14.0

### Breaking Changes
* The interface `Piwik\Settings\Interfaces\PolicyComparisonInterface` gained five methods used by the granular compliance dashboard: `getPolicySettingId()`, `isExternallyManagedByPolicyPage()`, `getWhatItDoes()`, `getImpact()` and `getPolicyOrder()`. Plugins that implement the interface directly must implement them. Plugins using `Piwik\Settings\Interfaces\Traits\PolicyComparisonTrait` (as all known implementers do) inherit default implementations and are not affected. `getPolicyOrder()` returns an order hint, lowest first, that decides where a compliance dashboard lists the setting, in the same way a menu item asks for its position; `PolicyManager::getAllControlledSettings()` now returns the settings in that order instead of in plugin discovery order, ordering settings that share a hint by their policy setting id. The trait's default, `PolicyComparisonInterface::POLICY_ORDER_LAST`, leaves a setting that does not ask for a position at the end of the list.
* Exporting a report for a single goal (a goals table or a bar/pie/evolution chart showing one goal's
  conversions or revenue) now returns only the columns shown in the UI, by adding `showColumns` to the
  export request. Previously the export returned the aggregated all-goals columns and every other
  goal's columns as well. Integrations that reuse an export URL copied from the UI will receive a
  narrower set of columns than before.
* The `Referrers_distinctWebsitesUrls` metric is now listed among the metrics of the `Referrers.get` report, carries the label `Distinct website URLs`, and is declared as a numeric metric. It was already archived and already part of `Referrers.get`'s own output, so that call returns the same columns as before; what changes is the surfaces driven by the report's metric list. `API.getProcessedReport` for `Referrers.get` now returns the metric instead of stripping it, and scheduled and emailed reports include it -- a new row in the HTML rendering, a new column in the CSV and TSV ones -- so consumers parsing those exports by column position will see a changed header and column count. Wherever a rendering resolves metric labels, `Distinct website URLs` now appears in place of the raw column name. Being declared numeric also brings it under CNIL data rounding, so on installations with that setting enabled the count is rounded to the same scale as other counts.
* The `UserCountry_distinctCountries` metric, returned by `UserCountry.getNumberOfDistinctCountries` and plotted by the distinct-countries sparkline widget on the Locations page, is now declared as a numeric metric and is therefore subject to CNIL data rounding. On installations with CNIL rounding enabled the returned count is rounded to the same scale as other counts instead of being passed through unrounded, so a value of `18` now reads as `20`. Installations without CNIL rounding are unaffected.
* The `Marketplace.searchPlugins` controller action now returns only the fields the plugin cards render, and the `plugins` template variable the `Marketplace.GetNewPlugins` and `Marketplace.GetPremiumFeatures` widgets pass to their templates has been reduced the same way. The version history, shop details, screenshots, support links, authors, changelog and activity they used to carry are served per plugin by the new `Marketplace.getPluginDetails` action instead, which the plugin details modal requests when it opens. A template overriding either widget has to fetch anything beyond the card fields itself.
* Tooltip content - the `title` of the hovered element, or the `data-tooltip` a report cell carries - may only use simple inline formatting (`b`, `br`, `em`, `i`, `small`, `span`, `strong`, `u`, without attributes). Content carrying anything else is displayed as text in full rather than rendered, so nothing is lost from it, but a `div`, an `img` or a `class` no longer has any effect. A report cell tooltip built from `<column>_tooltip` row metadata used to be inserted without a sanitizer and now shows markup as text. What a plugin returns from `Piwik\Plugins\Live\VisitorDetailsAbstract::renderActionTooltip()` for the `Live.renderActionTooltip` event is escaped where the entries are combined, so the visitor log's action tooltip shows that content as text even when it uses those tags; separate entries with a line break as before. Markup Matomo puts in a tooltip itself lost the classes it carried - `tooltip-action-*` in the visits log tooltip and `comparison-card-tooltip` in the comparison cards - since attributes are not kept; nothing in Matomo styled them, but a third-party theme might. Tooltips track the cursor and close as soon as it leaves their target, so their content was never interactive.

### New APIs
* `Piwik\Plugins\AIProviders` now implements provider-side web search, also called grounding, so an AI
  feature can ask the provider to search the web before answering and then read the sources it used.
  `Piwik\Plugins\AIProviders\AIRequest::withWebSearchEnabled()` is no longer advisory: Anthropic,
  Google and OpenAI honour it, while AWS Bedrock and the custom provider reject a grounded request with
  an `AIProviderClientException` rather than silently answering ungrounded. `AIProviderResponse` gained
  `wasWebSearchUsed()`, `getWebSearchCitations()`, `getWebSearchRequestCount()` and
  `getWebSearchQueries()`, backed by the new `Piwik\Plugins\AIProviders\WebSearchUsage`, which
  normalises the three providers' incompatible grounding shapes; `AIProviderService::canUseWebSearch()`
  and the new `supportsWebSearch` key of `getProviderStatusesForCaller()` let a feature check first.
  Citation titles and queries are untrusted model output, length-capped but otherwise verbatim, so
  escape them where they are rendered. Grounding is not a marginal cost: every provider charges per
  search and bills the retrieved page content as input tokens on top. See `plugins/AIProviders/README.md`
  for the per-provider caveats and the cost and timeout implications.
* `AIRequest::withTimeoutSeconds()` overrides the provider HTTP timeout, which now defaults to 120s for
  a grounded completion and stays at 30s otherwise. That outlasts the default read timeout of common
  web servers and proxies, so grounded completions are intended for CLI commands and scheduled tasks.
* `AIProviderResponse::getStopReason()` now reports a value for Google completions, which previously
  always returned `null`. Google's `finishReason` is mapped onto the same vocabulary the conversation
  API already uses (`STOP` becomes `end_turn`, `MAX_TOKENS` becomes `max_tokens`, `SAFETY` and
  `RECITATION` become `guardrail_intervened`), so it matches AWS Bedrock and Anthropic. OpenAI keeps
  reporting `stop` / `length` on both its grounded and ungrounded paths. A caller that treats an
  unrecognised stop reason as a failure will start seeing Google values.
* The new `Piwik\Http\SecurityHeaders::sendForDataResponse()` sends the header set for a response that is data rather than application UI: `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, `X-Frame-Options: deny` unless `[General] enable_framed_pages` allows embedding, and a `Content-Security-Policy` that allows no scripts, forms or base URI, only inline styles and images from Matomo itself (built by the new `Piwik\View\SecurityPolicy::restrictToDataResponse()`). Core sends it for the API endpoint itself, report exports, inline report previews, and the API module's `listAllMethods` and `listSegments` actions, which return HTML without a view; `action=listAllAPI`, which renders one, keeps the headers of a regular page. Call it in a plugin that streams an export or a report, before writing any output.
* Two new events let plugins customise the "No data has been recorded yet" page, on both the standalone page and its embedding in the reporting UI:
  * `Template.siteWithoutData.afterTrackingMethods` collects additional HTML rendered below the tracking methods list and the section for temporarily hiding the page.
  * `SitesManager.siteWithoutData.showInviteTeamMemberLink` lets a plugin hide the "Invite Team Member" link by setting the posted flag to `false`.
* The new `CoreHome.tooltipContent` renders the `title` of the hovered element as the content of a jQuery UI tooltip, and `window.vueSanitizeTooltip()` does the same for a value at hand in plain JavaScript. Both keep only the simple inline formatting a tooltip may show and fall back to displaying the whole value as text, so a title that was not written for a tooltip loses nothing while nothing in it is rendered.

### Deprecations
* `Piwik\Plugins\AIProviders\AIProviderResponse::isWebSearchEnabled()` is deprecated in favour of
  `wasWebSearchUsed()`, and the `webSearchEnabled` key of `AIProviderResponse::toArray()` in favour of
  the new `webSearchUsed` key. The name reads as request state, but both report what the provider
  actually did, while `AIRequest::isWebSearchEnabled()` keeps the request meaning. Both will be removed
  in Matomo 6.
* The `$webSearchEnabled` parameter of the `AIProviderResponse` constructor is deprecated. Pass a
  `Piwik\Plugins\AIProviders\WebSearchUsage` as the new trailing `$webSearch` parameter instead, which
  reports the searches, queries and citations a completion actually produced rather than a bare flag.
  The parameter keeps its position and its meaning, so positional callers written against Matomo 5.13.0
  keep working and a `true` still makes `wasWebSearchUsed()` report a search. It will be removed in
  Matomo 6.
* `Piwik\Plugins\AIProviders\Provider\AIProvider::isWebSearchUsed()` is deprecated. It was a
  placeholder whose base implementation always returned `false`, and no bundled provider overrode it,
  but a third-party provider that did override it controlled `AIProviderResponse::isWebSearchEnabled()`.
  Such a provider should now override `supportsWebSearch()` to declare the capability and pass a
  `WebSearchUsage` to `buildResponse()`. An existing override is still honoured by
  `wasWebSearchUsed()` for the transition, and will stop being consulted in Matomo 6.

### HTTP API
* A new `keep_flattened_dimension_columns` parameter keeps the columns a flattened report adds for its
  dimensions when the request also restricts columns with `showColumns`. Flattening with
  `flat=1&show_dimensions=1` adds one column per dimension, but their names only exist after
  flattening, so a caller cannot include them in a `showColumns` allowlist and `ColumnDelete` would
  drop them. Setting `keep_flattened_dimension_columns=1` re-adds them after flattening. It defaults
  to `0`, so `showColumns` on its own behaves exactly as before.

## Matomo 5.13.0

### Breaking Changes
* Site content detection (used by the tracking-code setup page and consent-manager detection) now fetches the site URL over the SSRF-safe request path. It refuses targets resolving to private, loopback or reserved IP addresses, and requires the curl extension instead of falling back to the `fopen` or `socket` transports. Installations tracking intranet sites on private addresses must allowlist their ranges via the new `[General] allowed_private_egress_ranges` setting. Refusals are logged at `WARN` level. A configured `[proxy] host` also makes these requests fail closed, as the proxy resolves the target itself and the validated IP cannot be pinned. Where the site host is reachable directly, add it to `[proxy] exclude` (exact hostnames, no wildcards).
* A report or graph can now only be streamed to the browser by the top-level request. `ImageGraph.get` and `ScheduledReports.generateReport` throw when a streaming output mode comes from a nested API request, for example an `API.getBulkRequest` sub-request. Use `GRAPH_OUTPUT_PHP`/`GRAPH_OUTPUT_FILE` or `OUTPUT_RETURN` instead — `OUTPUT_SAVE_ON_DISK` is rewritten to `OUTPUT_DOWNLOAD` and still throws. The streaming methods of `Piwik\ReportRenderer` and `Piwik\ReportRenderer\Pdf` throw too, so a plugin's own renderer inherits the restriction (new: `ReportRenderer::checkStreamingToBrowserIsAllowed()` and `Piwik\API\Request::isCurrentApiRequestNestedInAnotherApiRequest()`).
* `UsersManager.createAppSpecificTokenAuth` now only creates a token for the account the caller is acting as, with no exception for super users — including code inside `Piwik\Access::doAsSuperUser()`, console commands and scheduled tasks. To create a token for another account, send an unauthenticated request with that account's `passwordConfirmation`. The method also refuses to run as a nested API request.
* `UsersManager.setUserAccess` now requires `passwordConfirmation` to grant the `admin` role, in either the string or the array form of `access`, on top of the existing check for granting the anonymous user `view` access. As before this applies only to session-authenticated requests, which includes any request sending `force_api_session=1`; plain `token_auth`, `Authorization: Bearer` and CLI calls are unaffected.

### New APIs
* The sparklines visualization has been redesigned as a responsive card grid of metric tiles. Plugin-facing additions that come with it:
  * The new `Piwik\Plugins\CoreVisualizations\Visualizations\Sparklines\Config::$use_metric_labels_as_titles` property lets a sparklines view use its own metric translations as the card titles instead of the generic metric names. Intended for views that relabel shared columns with section-specific names, e.g. the Ecommerce Overview.
  * The `sparkline(src, width, height)` Twig helper accepts optional `width`/`height` display-size parameters (in px, defaults `Piwik\Visualization\Sparkline::DEFAULT_WIDTH`/`DEFAULT_HEIGHT`); the sparkline PNG is rendered at twice the displayed size for hi-DPI screens.
* Table visualizations gained a `show_percentage_values` request property (`Piwik\Plugins\CoreVisualizations\Visualizations\HtmlTable\RequestConfig`). When enabled, eligible metric cells display the percentage of the report total and show the absolute value on hover instead of the other way around. It defaults to `false`, can be set by a plugin or passed as a query parameter, and is exposed to users as a setting in the report's configure menu. Whether that setting is offered is derived from the report itself into the read-only display property `report_supports_percentage_values`, which is true when at least one displayed column appears in both `report_ratio_columns` and the report totals.
* `Piwik\Http::sendHttpRequest()` and `Piwik\Http::sendHttpRequestBy()` accept a new optional `$validateEgressIp`
  parameter enabling an SSRF-safe request path (public-IP validation, redirect re-validation, IP pinning). Use it
  whenever the target URL derives from untrusted input, such as a site's configured URL. Requires curl.
  Installations tracking intranet sites on private addresses can allowlist their ranges via the new
  `[General] allowed_private_egress_ranges` INI setting. A refused target or unmet precondition throws the new
  `Piwik\Http\EgressBlockedException`, so callers can tell a policy rejection from a transient network failure.
* The `Http.sendHttpRequest` and `Http.sendHttpRequest.end` events pass a new `validateEgressIp` entry in their params
  array. A listener that resolves the request itself must either honour SSRF-safe semantics (public-IP-only target,
  re-validated redirects) or leave the request unhandled.
* Evolution line graphs now draw a forecast for incomplete periods, on by default. `Piwik\Plugins\CoreVisualizations\Visualizations\JqplotGraph\Evolution\Config` gained `$show_forecast` (default `true`) and `$disable_forecast` (default `false`); turning either one off skips the forecast and the sub-period API requests it needs. A subclass that renders bars must set `$this->config->show_line_graph = false` in `beforeLoadDataTable()` before calling the parent, or it pays for a forecast the bar renderer cannot draw. Only the rendered graph changes, no API response.
* The new `Piwik\Columns\Join::getAdditionalKeyColumns()` lets a dimension join require further columns to match on both tables, for a join column that is not unique on its own — `Piwik\Columns\Join\GoalNameJoin` uses it to scope its join to `idsite`. It returns an empty array by default, so existing joins are unaffected.
* The new bundled `AIProviders` plugin holds the AI provider credentials and defaults that Matomo's AI features use, and lets a plugin add a provider of its own by extending `Piwik\Plugins\AIProviders\Provider\AIProvider`:
  * `AIProviders.addAIProviders` registers providers on the `AIProvidersList` it receives. `AIProviders.filterAIProviders` can remove one or mark it restricted, so it still serves completions but is hidden from the admin UI. The first registration for a provider ID wins.
  * `Piwik\Plugins\AIProviders\AIProviderService` runs a completion (`complete()`) or a multi-turn conversation (`converse()`).

### New config.ini.php settings
* The new `[AIProviders]` section configures the AI provider plugin from the config file:
  * `defaultProvider` and `defaultCapabilityLevel` (`instant` or `thinking`) pin the instance-wide defaults. Pinning either one makes the plugin's settings page read-only and hides it from the admin menu.
  * `<providerId>ApiKey`, `<providerId>EndpointUrl`, `<providerId>Model` and `<providerId>UseFipsEndpoint` pin per-provider credentials for `anthropic`, `google`, `openai`, `bedrock` and `custom-provider` (`EndpointUrl` applies to the last two, `UseFipsEndpoint` to `bedrock`). Each is also readable from the matching `MATOMO_AIPROVIDERS_<PROVIDER_ID>_*` environment variable. The config file wins over the environment variable, and both win over the UI.
  * `providerSelectionAllowlist[]` exempts the named plugins from a pinned `defaultProvider`, letting them target a provider of their choice. It does nothing unless `defaultProvider` is set.

### HTTP API
* `API.getBulkRequest` now validates the authentication parameters of each nested request URL against
  the outer request. Within a browser session a nested request may change neither the session flag
  (`force_api_session`) nor the acting user (`token_auth`); outside a session a nested request may still
  authenticate with its own `token_auth`, but may not change the session flag. A nested request whose
  parameters conflict with the outer request's authentication context aborts the whole bulk request.
* `API.getProcessedReport` for `Referrers.getAll` now returns `reportTotal` keyed by metric name instead of raw `Piwik\Metrics::INDEX_*` integers such as `2` and `3`. It was the only report leaking those keys.

### HTTP Tracking API
* `token_auth` and `token` are now part of the default `url_query_parameter_to_exclude_from_url`, so both are stripped from tracked page, site search, event, content, goal-conversion and referrer URLs; downloads and outlinks keep them. An installation that sets the option in its own `config.ini.php` replaces the default rather than extending it, and has to add the two names itself.

## Matomo 5.12.0

### JavaScript Tracker

#### New APIs
* The methods `setIgnoreCampaignAttributionForSources` and `getIgnoreCampaignAttributionForSources` have been added to
  the JavaScript tracker. They allow setting/getting sources whose campaign values in the current URL should be ignored 
  for attribution. Matching campaign parameters are still kept in the tracked URL/request.

### New APIs
* `Record::setAggregatedRecordTransform()` lets a blob record register a callback that is applied to its aggregated
  table during non-day archiving, after the day blobs are aggregated together and before the table is truncated and
  stored. Use it together with `Record::setBlobColumnAggregationOps()` (marking a column `'skip'`) to recompute columns
  that cannot be summed across child periods — for example a table-relative ratio, index or score — so they can also be
  used as the sort column for truncation. It applies on both the standard blob path and the built-from-flat path
  (`Record::setBuiltFromFlatRecord()`), where the flat base record and the hierarchy rebuilt from it are each
  transformed on their own table. A matching optional `$postAggregationTransform` parameter was added to
  `ArchiveProcessor::aggregateDataTableRecords()`.
* The reporting menu can now be split into several top-level sections (in addition to the default
  "Analytics" menu). A category declares which section(s) it belongs to via `Category::setGroups()`
  (and the protected `$groups` property); `API.getReportPagesMetadata` now exposes a `groups` field per
  category. Each non-default group automatically gets a top-menu entry that opens the regular reporting
  single-page-app filtered to that group (the active section is carried in the URL hash), so reports stay
  within the same SPA and quick search. The first such section, "AI Insights", surfaces the existing
  AI Assistants reports.

### New config.ini.php settings
* `datatable_archiving_maximum_rows_actions_flat` caps the number of rows used when flat-archiving
  page/title Actions reports before the hierarchy is rebuilt (set to `0` to keep the legacy
  hierarchical-only Actions archiving). See `Record::setAggregatedRecordTransform()` above.
* `datatable_archiving_maximum_rows_ai_chatbot_content` caps the number of content URLs
  (pages/documents) listed in the AI Chatbots Content Requests reports.
* `datatable_archiving_maximum_rows_ai_chatbot_favoured_pages` caps the number of page URLs listed in
  the Human-Favoured / AI-Favoured Pages reports.
* `live_ai_chatbots_maximum_rows` caps the number of AI chatbots listed in the real-time AI Chatbots
  reports.
* `live_ai_chatbots_top_page_urls_maximum_rows` caps the number of page URLs listed in the real-time
  AI Chatbots top page URL reports.

## Matomo 5.11.0

### New APIs
* `SitesManager.addSite` and `SitesManager.updateSite` now accept an optional `description` parameter (up to 255 characters). Site entities
  returned by the SitesManager APIs now include a `description` field.
* `CustomDimensions.configureNewCustomDimension` and `CustomDimensions.configureExistingCustomDimension` now accept an optional `description`
  parameter (up to 1000 characters) to provide additional context for a custom dimension.
* New ViewDataTable display properties were added: `Config::$report_supports_flatten`, `Config::$show_flatten_table_export` and
  `Config::$export_parameters_to_modify` / `RequestConfig::$export_parameters_to_modify`, allowing reports to control flattening availability and
  export link parameters independently of the UI.
* New Vue components are exported from CoreHome for use by plugins: `MatomoModal`, `DraggableList` and `SearchInput`.
* Themes can now customize the alternative border color using `@theme-color-border-alternative`.

### HTTP API
* `ScheduledReports.sendReport` now accepts `range` as `period` parameter.
* CSV/TSV exports now replace carriage return characters in values with spaces (in addition to tabs).

### Deprecations
* The theme variable `@theme-color-border` (`ThemeStyles::$colorBorder`) is deprecated; use `@theme-color-border-alternative` instead.

## Matomo 5.10.0

### New APIs
* Widgets can now be declared as client-rendered through `WidgetConfig::setClientSideComponent()` and `WidgetConfig::setClientSideProps()`. `API.getWidgetMetadata` and `API.getReportPagesMetadata` now expose a `clientComponent` field for these widgets, and Widgetize/dashboard rendering supports bootstrapping them without an extra widget controller request.

### Deprecations
* The methods `ArchiveTableCreator::getNumericTable()` and `ArchiveTableCreator::getBlobTable()` now support a `$createIfMissing` parameter. Omitting this parameter is deprecated; pass `true` to create missing archive tables or `false` to return only existing tables. In Matomo 6 the default behavior for omitted calls will change to lookup-only.

## Matomo 5.9.0

### New APIs
* `UsersManager.logoutUser` was added to sign a user out of all sessions.

### Deprecations
* The jQuery UI `liveWidget` API (`$.fn.liveWidget`) is now deprecated and will be removed in Matomo 6. Use `Live.AutoRefreshWidget` vue component instead.

## Matomo 5.8.0

### Breaking Changes
* API requests that provide conflicting authentication values for `token_auth` or `force_api_session` across request sources (for example GET and POST) now fail with `400 Bad Request` instead of applying precedence.
* Category names returned by `API.getReportMetadata` were updated to match UI terminology. Plugin integrations expecting old names may break:
    - `Actions` is now `Behaviour`
    - `Referrers` is now `Acquisition`
* `AjaxHelper` no longer supports `returnResponseObject` for bulk requests (`API.getBulkRequest` / array-based `AjaxHelper.fetch`). Bulk requests now always resolve to merged response data.


### New config.ini.php settings
* `API_bulk_request_limit` sets the maximum number of URLs allowed in `API.getBulkRequest` for authenticated users (-1 disables the limit).

### HTTP API
* `API.getBulkRequest` now enforces request limits (10 for anonymous users without view access, 50 for anonymous users with view access, or the lower configured limit if `API_bulk_request_limit` is set).

## Matomo 5.7.1

### Breaking Changes
* HTTP APIs that accept `idSite` now validate it more strictly. Invalid values that were previously ignored can now trigger a 400 Bad Request, and some endpoints now enforce integer `idSite` parameters (e.g., non-numeric values may raise a TypeError).

## Matomo 5.7.0

### Breaking Changes

* Client-side faults now map to consistent 4xx responses:
  - Missing/invalid API params return 400
  - Invalid actions return 404
  - Missing chunks return 404
  - Missing plugins return 404
  - Deactivated plugins return 403

### New config.ini.php settings
* Proxy scheme headers (like `X-Forwarded-Proto`) are now configurable via `proxy_scheme_headers`.

### New Features

* New event `PrivacyManager.deleteDataSubjectsForDeletedSites` to enable plugins to be GDPR compliant, when tracking visit unrelated data.

### HTTP Tracking API

* The new Bot Tracking plugin now supports analyzing requests from AI bots. See https://developer.matomo.org/api-reference/tracking-api#tracking-bots for supported tracking parameters.


## Matomo 5.6.0

### New Features

* Themes can now customize the focus ring colors using `@theme-color-focus-ring` (used globally) and `@theme-color-focus-ring-alternative` (used in header navigation on solid background).


## Matomo 5.5.0

### Breaking Changes

* Annotations were moved to their own database table. Plugins trying to access annotations without using the API might need to be updated.
* AI Assistants are now detected as new referrer type (ID=8), which allows improved reports and better segmentation

### JavaScript Tracker

* A new method `setReferralUrlMaxLength` has been added. It allows limiting the referral cookie size.


## Matomo 5.4.0

### Authentication changes

Matomo now supports providing authentication using Bearer header tokens. Instead of sending your auth token as GET or POST param, you can use a header like `Authorization: Bearer myAuthToken`.

### Breaking Changes

The ImageGraph URLs returned by some of our APIs do no longer contain the `token_auth`. If you are using such URLs to e.g. directly fetch their content, you may need to adjust your implementation to append a valid `token_auth` again.

### New APIs

The new API parameter `showMetadata` was introduced. In can be used to toggle displaying of metadata in API exports. The default value is `1` to keep current behavior.

### JavaScript Tracker

#### New APIs

* The methods `setIgnoreCampaignsForReferrers` and `getIgnoreCampaignsForReferrers` have been added to the JavaScript tracker. They allow to set/get referrers for which campaign parameters should be ignored. For more details see [Configuration of JavaScript tracker](https://developer.matomo.org/api-reference/tracking-javascript#configuration-of-the-tracker-object) documentation.


## Matomo 5.3.0

### Breaking Changes

* When requesting goals for multiple sites at once using `Goals.getGoals`, the result will no longer be indexed by `idgoal`. Requesting the goals for a single site will still return them indexed by `idgoal`.
* The SEO widget does no longer serve the metric `Google indexed pages`. As Google search is no longer accessible without JavaScript this metric can no longer be fetched.

### New APIs

* The method `getNthLevelTableDimension` has been added to the `Report` class. This extends support for subtable reports for more than three levels.
* Commands can subscribe to system signals by defining a `getSystemSignalsToHandle` function in the command implementation. This feature is gated behind the "SystemSignals" feature flag, signal subscription will be silently disabled unless that feature flag is enabled.

### Deprecations

* The method `Report::getThirdLeveltableDimension` has been deprecated. Use `Report::getNthLevelTableDimension(2)` instead.

### New commands

* New command `core:reset-invalidations` allows administrators to reset stuck invalidations that are incorrectly marked as "in progress".


## Matomo 5.2.0

### Breaking Changes

* The MultiSites API has been reworked. The previously incorrectly named metrics for the previous period now have correct names:
    * `previous_Actions_nb_pageviews` => `previous_nb_pageviews`
    * `previous_Goal_revenue` => `previous_revenue`
    * `previous_Goal_nb_conversions` => `previous_nb_conversions`
    * `previous_Goal_0_nb_conversions` => `previous_orders`
    * `previous_Goal_0_revenue` => `previous_ecommerce_revenue`

### Deprecations

* The methods `Db::isOptimizeInnoDBSupported`, `Db::optimizeTables` have been deprecated. Use `Db\Schema::getInstance()->isOptimizeInnoDBSupported` and `Db\Schema::getInstance()->optimizeTables` instead
* The method `TransactionLevel::setUncommitted` has been deprecated. Use `TransactionLevel::setTransactionLevelForNonLockingReads` instead
* The method `Piwik\Plugins\SitesManager\API::setGlobalExcludedQueryParameters` has been deprecated. Use `Piwik\Plugins\SitesManager\API::setGlobalQueryParamExclusion` instead

### New commands

* New command `plugin:install-or-update` lets you install or update a plugin from the Marketplace.

## Matomo 5.1.0

### Breaking Changes

* The `errorlog` (`\Monolog\Handler\ErrorLogHandler`) and `syslog` (`\Monolog\Handler\SyslogHandler`) handlers are no longer directly used. Plugins using or overwriting those handlers using DI should now use the scoped classes `Piwik\Plugins\Monolog\Handler\ErrorLogHandler` and `Piwik\Plugins\Monolog\Handler\SyslogHandler` instead.
* The dependency `jQuery.dotdotdot` has been removed. Please use pure CSS instead or include the library in your plugin if needed.

### Deprecations

The API method `Overlay.getExcludedQueryParameters` has been deprecated and will be removed in Matomo 6. Use the new method `SitesManager.getExcludedQueryParameters` instead.

### JavaScript Tracker

#### New APIs

* The method `disableCampaignParameters` have been added to the JavaScript tracker. It allows to disable processing of campaign parameters and forwarding them to the tracking endpoint.

## Matomo 5.0.0

### Breaking Changes

* 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 the `JSON` renderer, which behaves the same.
* The javascript event `piwikPageChange`, which is triggered when a reporting page is loaded, has been renamed to `matomoPageChange`. Ensure to update your implementation if you rely on it.
* The deprecated javascript functions `broadcast.init`, `broadcast.propagateAjax` and `broadcast.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 than `a-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://` protocol is no longer tracked. To enable tracking of the `file://` protocol use the new JavaScript tracker method `enableFileTracking` ([learn more](https://matomo.org/faq/how-to/why-is-no-data-tracked-for-local-files/)).
* 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 methods `setCompleted()`, `isCompleted()`, `skipChallenge()` and `isSkipped()` in the `Piwik\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 of `Monolog\Logger`
  * Use `Piwik\Log\LoggerInterface` instead of `Psr\Log\LoggerInterface`
  * Use `Piwik\Log\NullLogger` instead of `Psr\Log\NullLogger`
  * Use `Piwik\DI` instead of `DI`
    * `DI` namespaced functions need to be replaced with static `Piwik\DI` methods. E.g. `DI\add()` will become `Piwik\DI::add()`
    * If you need to catch dependency related exceptions use `Piwik\Exception\DI\DependencyException` or `Piwik\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` or `DI\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` or `initialize` can no longer be overwritten. Instead, use our custom methods prefixed with `do`: `doExecute`, `doInteract` or `doInitialize`
      * `doExecute()` method needs to return integers. We recommend using the class constants `SUCCESS` or `FAILURE` as return values.
    * Where ever you need to work with input or output use `$this->getInput()` or `$this->getOutput()` instead. Don't use `InputInterface` or `OutputInterface` as method typehints.
    * When defining input options and arguments `addOption` and `addArgument` can no longer be used
      * For arguments use `addOptionalArgument` or `addRequiredArgument`
      * For options use `addNegatableOption`, `addOptionalValueOption`, `addNoValueOption` or `addRequiredValueOption`
    * Directly using any console helpers is now prohibited
      * When needing user input use the new methods `askForConfirmation`, `askAndValidate` or `ask`
      * For progress bars use the methods `initProgressBar`, `startProgressBar`, `advanceProgressBar` and `finishProgressBar`
      * Tables can be rendered using the new method `renderTable`
    * For executing another command within your command use the new method `runCommand`
* 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.

### New APIs

* 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 of `Common::getRequestVar`.
* All API are now able to overwrite the property `$autoSanitizeInputParams`. Setting this variable to `false` will prevent an automatic apply of `Common::sanitizeInputValues` on all parameter passed to the API methods. By now this property defaults to `true`, but this might change in upcoming major releases.
* 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

### Deprecations

* The method `Common::getRequestVar` is now deprecated, but will remain API until Matomo 6. You may already start using the new class `Piwik\Request` instead, but ensure to handle needed sanitizing / escaping yourself.
* The brand related less variables for colors `color-black-piwik`, `color-blue-piwik`, `color-red-piwik` and `color-green-piwik` are now deprecated and will be removed in Matomo 6. New variables where `piwik` was replaced with `matomo` have been introduced. E.g. `color-black-matomo`
* Support for jQuery UI is now deprecated and might be removed in one of the next major releases. Please consider using Materialize CSS or Vue.js instead.

### Removed Config

* 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 options `segments_subquery_cache_ttl` and `segments_subquery_cache_limit` have also been removed.

### Other Breaking changes

* 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.

### Archiving
* When posting the event `Archiving.getIdSitesToMarkArchivesAsInvalidated` started passing date, period ,segment and name parameter along with idSites parameter.

### Updated commands
* 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

### Usage of authentication tokens
* 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 to `0`, has been added. Enabling this option will prevent any use of tokens in GET API requests.

## Matomo 4.14.0

### HTTP Tracking API

* 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 campaign parameters to the tracked URL instead.

## Matomo 4.13.1

### New config.ini.php settings
* 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.

## Matomo 4.13.0

### New config.ini.php settings
* A new config setting `enable_opcache_reset` defaulting to `1`. Provides a configuration switch for `opcache_reset` when general caches are cleared. This may be useful for multi-tenant installations that would rather manage opcache resets by themselves. This could also be used by scripts to temporarily switch off opcache resets.

## Matomo 4.12.0

### Breaking Changes

* When removing a user through the `UsersManager.deleteUser` API using a session authentication, a new parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.
* When adding a user through the `UsersManager.addUser` API using a session authentication, a new parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.
* When inviting a user through the `UsersManager.inviteUser` API using a session authentication, a new parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.

### New PHP events

* 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 parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.

### New Privacy Opt-Out Options

* 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.     

### JavaScript Tracker

#### New APIs

* The methods `setExcludedReferrers` and `getExcludedReferrers` have been added to the JavaScript tracker. They allow setting and receiving the referrers the JavaScript tracker should ignore. If a referrer matches an entry on that list, it will not be passed with the tracking requests and the attribution cookie will stay unchanged. This can for example be used if you need to forward your users to an external service like SSO or payment and don't want any visits or conversions being attributed to those services.

## Matomo 4.11.0

### Breaking Changes

* 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.

### New config.ini.php settings
* 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.

#### New PHP events

* 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.


## Matomo 4.10.0

### Breaking Changes

* 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. Therefore `json` will no longer be included in the list of static file extensions in generated `.htaccess` files.

## Matomo 4.8.0

### New config.ini.php settings

* The config setting `enable_default_location_provider` in `Tracker` has been added. By setting this option to 0, you can disable the default location provider. This can be used to prevent the geolocator to guess the country based on the users language, if the configured provider doesn't provide any results.

#### New PHP events

* Added new event `Segment.filterSegments`. Plugins can use this to filter segment definitions.

## Matomo 4.7.0

### Deprecated APIs

* The `piwik-field` and related directives have been converted to Vue and the `template-file` attribute is now considered deprecated and will be removed in Matomo 5. Instead,
  the `component` property should be used to add a new form field, it should be an object with two properties that reference a Vue component, `plugin` and `name`, where `plugin`
  is the plugin the Vue component is located in and `name` is the Vue name of the component's export. 

### New Change Notifications

* 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.](https://developer.matomo.org/guides/providing-updates) 


## Matomo 4.6.0

### New Framework

* We have begun introducing Vue 3 as the frontend framework to replace AngularJS. You can learn more about it in [our developer guide.](https://developer.matomo.org/guides/working-with-piwiks-ui)

### New APIs
* 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 member `securityPolicy` so plugins can use `$this->securityPolicy` to access these new methods when a custom Content Security Policy is needed.

### Breaking Changes

* 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 E-commerce feature is disabled for a site, then the Live API no longer returns the E-commerce related visitor properties `totalEcommerceRevenue`, `totalEcommerceConversions`, `totalEcommerceItems`,  `totalAbandonedCartsRevenue`, `totalAbandonedCarts` and `totalAbandonedCartsItems`.
* Content Security Policy (added in Matomo 4.4.0) is no longer in Report Only mode by default. 

### New config.ini.php settings

* The config setting `contact_email_address` in `General` has been added. It will be used as contact email address for users. If not defined (default) all email addresses of all super users will be used instead, which equals the behavior it used to be.

## Matomo 4.4.0

### Breaking Changes

* The `logme` method for [automatic logins](https://matomo.org/faq/how-to/faq_30/) is now disabled by default for new installations. For existing installations it will be enabled automatically on update. If you do not need it please consider disabling it again for security reasons by setting `login_allow_logme = 0` in `General` section of `config.ini.php`.
* The redirect using the `url` param for the automatic login action `logme`, will no longer do redirects to untrusted hosts. If you need to do redirects to other URLs on purpose, please add the according hosts as `trusted_hosts` entry in `config.ini.php`

### New config.ini.php settings

* 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 to `1`. 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.](https://matomo.org/faq/troubleshooting/faq_115/)

### New commands

* Added new command `core:version` which returns the Matomo version number.

## Matomo 4.3.1

### New commands

* 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).

## Matomo 4.3.0

### JavaScript Tracker

#### Breaking changes in Matomo JS tracker

* 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 the `addListener` method to add event listener manually after the DOM has changed and the `enableLinkTracking` is turned on we will track the click event for that element twice.

### Breaking Changes

* 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.

### Upcoming Breaking Changes

* 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.

### New config.ini.php settings

* The `password_hash_algorithm`, `password_hash_argon2_threads`, `password_hash_argon2_memory_cost` and `password_hash_argon2_time_cost` INI config options have been added to allow using specific `password_hash` algorithms and options if desired.
* The `enable_php_profiler` INI config option was added. This must now be set to 1 before profiling is allowed in Matomo.

## Matomo 4.2.0

### New config.ini.php settings

* A config setting `geolocation_download_from_trusted_hosts` was introduced. Downloading GeoIP databases will now be limited to those configured hosts only.

## Matomo 4.1.1

### Changed config.ini.php settings

* The config settings `login_password_recovery_email_address` and `login_password_recovery_name` have been removed to avoid possible smtp problems when sending recovery mails. `noreply_email_address` and `noreply_email_name` will be used instead.

## Matomo 4.0.0

### JavaScript Tracker

#### Breaking changes in Matomo JS tracker

* 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 method `disableAlwaysUseSendBeacon`. As a result, callback parameters won't work anymore and a tracking request might not appear in the developer tools. This will improve the load time of your website. Tracking requests will be sent as POST request instead of GET but the parameters are by default included in the URL so they don't go lost in a redirect. 
* The JS tracker event `PiwikInitialized` has been renamed to `MatomoInitialized`
* 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 of `piwikPluginAsyncInit`
* 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.

#### Deprecations in Matomo JS tracker

* The JS Tracker method `getPiwikUrl` has been deprecated and `getMatomoUrl` should be used instead.
* The JS Tracker init method `piwikAsyncInit` has been deprecated and `matomoAsyncInit` should be used instead.
* The JS object `window.Piwik` has been deprecated and `window.Matomo` should be used instead.

#### Recommendations for Matomo JS tracker

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 with `matomo_ignore` 
* If using the `piwik_download` css class to mark a link as download we recommend replacing it with `matomo_download` 
* If using content tracking, we recommend replacing the following CSS classes should they be used `piwikTrackContent`, `piwikContentPiece`, `piwikContentTarget`, and `piwikContentIgnoreInteraction` with `matomoTrackContent`, `matomoContentPiece`, `matomoContentTarget`, and `matomoContentIgnoreInteraction`. 
* We also encourage using the `matomo.js` JS tracker file instead of `piwik.js` and `matomo.php` tracker endpoint instead of `piwik.php` endpoint.

#### New APIs
* A new JS tracker method `getMatomoUrl` has been added which replaces `getPiwikUrl`.

### HTTP APIs

#### Breaking changes in HTTP API 

##### Format changes
* 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 the `JSON` renderer. 
* The `JSON` renderer now behaves like the previous `JSON2` renderer did. This means arrays like `['a' => 0, 'b' => 1]` will be rendered in JSON as `{"a":0,"b":1}` instead of `[{"a":0,"b":1}]`. This impacts these API methods:
  * 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 (eg `5`). In this case the response will be no longer `5` but for example `{value: 5}`

##### Method changes
* The API method `UsersManager.getTokenAuth` has been removed. Instead you need to use `UsersManager.createAppSpecificTokenAuth` and store this token in your application.
* The API method `UsersManager.createTokenAuth` has been removed. Instead you need to use `UsersManager.createAppSpecificTokenAuth` and store this token in your application.
* The API method `DevicesDetection.getBrowserFamilies` has been removed. Instead you need to use `DevicesDetection.getBrowsers`
* The API method `CustomPiwikJs.doesIncludePluginTrackersAutomatically` has been renamed to `CustomJsTracker.doesIncludePluginTrackersAutomatically`
* The API method `Live.getLastVisitsForVisitor` has been removed. Use `Live.getVisitorProfile` instead.
* The API method `Live.getLastVisits` has been removed. Use `Live.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` and `Referrers.getKeywordsForPageTitle`. Use `Referrers.getKeywords` instead in combination with a `entryPageUrl` or `entryPageTitle` segment.
* The parameter `alias` from the API methods `UsersManager.addUser` and `UsersManager.updateUser` has been removed.

#### HTTP Tracking API

* An optional new tracking parameter called `ca` has been added which can be used for tracking requests that aren't page views see [#16569](https://github.com/matomo-org/matomo/issues/16569)

### PHP Plugin API

#### New PHP events

* Added new event `Db.getTablesInstalled`, plugins should use to register the tables they create.

#### Breaking changes in PHP events

* The event `CustomPiwikJs.piwikJsChanged` has been renamed to `CustomJsTracker.trackerJsChanged`
* The event `CustomPiwikJs.shouldAddTrackerFile` has been renamed to `CustomJsTracker.shouldAddTrackerFile`
* The event `CustomMatomoJs.shouldAddTrackerFile` has been renamed to `CustomJsTracker.manipulateJsTracker`
* The event `Live.getAllVisitorDetails` has been removed. Use a `VisitorDetails` class instead (see Live plugin).
* The event `Live.getExtraVisitorDetails'` has been removed. Use the `VisitorDetails` class within each plugin instead.
* The event `Piwik.getJavascriptCode` has been renamed to `Tracker.getJavascriptCode`.
* The event `LanguageManager.getAvailableLanguages` has been removed. Use `LanguagesManager.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.

#### Removed methods and constants in PHP Plugin API

* 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. Use `json_encode()` instead
* The method `\Piwik\Common::json_decode()` has been removed. Use `json_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. Use `Piwik\Metrics\Formatter` or `Piwik\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. Use `DimensionsProvider::factory` instead.
* The method `Piwik\Config::reset` has been removed. Use the `reload` method instead.
* The method `Piwik\Config::init` has been removed. Use the `reload()` method instead.
* The method `Piwik\Db::getColumnNamesFromTable` has been removed. Use the `TableMetadata::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. Use `Piwik\Date::getDatetimeFromTimestamp` instead.
* The method `Dimension::addSegment()` has been removed. See new implementation of `DimensionSegmentFactory::createSegment` for a replacement
* The constant `Piwik\Plugins\Goals\API::NEW_VISIT_SEGMENT` has been removed. Use `Piwik\Plugins\VisitFrequency\API::NEW_VISITOR_SEGMENT` instead.
* The signature of `Dimension::configureSegments()` has been changed. Similar to configuring Metrics it now takes two parameters `SegmentsList $segmentsList` and `DimensionSegmentFactory $dimensionSegmentFactory`.
* The signature of the event `Segment.addSegments` has been changed. It now has one parameter `SegmentsList $list`, which allows adding new segments to the list
* The core plugin `CustomPiwikJs` has been renamed to `CustomJsTracker`
* The class `Piwik\Plugins\CustomPiwikJs\TrackerUpdater` has been renamed to `Piwik\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.
  
#### New APIs
* 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 setting `hideColumnsRecursively=1`. For all `Live` api methods this is the default behaviour.

### Other Breaking changes

* 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 with `view` 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. Use `matomo` 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 attribute `rel="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 parameter `matomo_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]((https://php-di.org/doc/migration/6.0.html)):
  * 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.

### New config.ini.php settings

* `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.


## Matomo 3.14.0

### New API

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

## Matomo 3.13.6

### API Changes
* The first parameter `userLogin` in the `UsersManager.getUserPreference` method is now optional and defaults to the currently authenticated user login.

## Matomo 3.13.5

### New API
* 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.

## Matomo 3.13.1

### Deprecations
* 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 

## Matomo 3.13.0

### New API
* 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.

### Other Changes
* 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.

## Matomo 3.12.0

### New API
* Added new event `Visualization.beforeRender`, triggered after immediately before rendering a visualization.
* Added new event `Http.sendHttpRequest` and `Http.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

## Matomo 3.10.0

### Breaking Changes
* When giving a user superuser access through the `UsersManager.setSuperUserAccess` API, a new parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.
* 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 calling `setCustomDimension`, your custom dimension values appearing in reports and Visits log/Visitor profile may now be double URL encoded. To solve the double encoding issue, you can remove your URL encoding and trust that Matomo JavaScript Tracker will URL encode the values correctly.

### New APIs
* 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.

## Matomo 3.9.0

### Breaking Changes
* `Referrers.getKeywordsForPageUrl` and `Referrers.getKeywordsForPageTitle` APIs have been deprecated and will be removed in Matomo 4.0.0
* By default, Matomo [application logs](https://matomo.org/faq/troubleshooting/faq_115/) will now be logged in `tmp/logs/matomo.log` instead of `tmp/logs/piwik.log`. This log file path can be edited in your config/config.ini.php in the INI setting `logger_file_path`.

### New Features
* 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 APIs
* New API methods `Piwik\Plugin\Manager::getPluginsDirectories()` and  `Piwik\Plugin\Manager::getPluginDirectory($pluginName)` have been added as it is now possible to locate Matomo plugins in different directories and it should be no longer assumed a plugin is located in the "/plugins" directory.
* 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. Use `LanguagesManager.getAvailableLanguages` instead.

## Matomo 3.8.0

### Breaking Changes
* When changing the email address or the password through the `UsersManager.updateUser` API, a new parameter `passwordConfirmation` needs to be sent along with the request containing the current password of the user issuing the API request.
* 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. Use `Piwik\Access::doAsSuperUser` instead.

### New APIs

* 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.

### New Features
* 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.

### Internal change
* 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.

### Deprecations
* The method `Piwik\SettingsPiwik::isPiwikInstalled()` has been deprecated and renamed to `isMatomoInstalled()`. It is still supported to use the method, but the method will be removed in Piwik 4.0.0

## Matomo 3.6.1

### New APIs

* 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.

### New Developer Features

* 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 to `1` to enable logging for all tests. The `tests:run` and `tests:run-ui` commands now both have an `--enable-logging` option to enable logging for a specific run.

## Matomo 3.6.0

### New Features

* A new role has introduced called "write" which has less permissions than an admin but more than a view only user ([see FAQ](https://matomo.org/faq/general/faq_26910/)).
* 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.

### New config.ini.php settings

* `archiving_profile = 0`, if set to 1, core:archive profiling information will be recorded in a log file. the log file is determined by the `archive_profiling_log` option.
* `archive_profiling_log = `, if set to an absolute path, core:archive profiling information will be logged to specified file.
* `enable_internet_features=0` will now fully disable Internet access by preventing all outgoing connections. Note: changing this setting is not recommended for security, because you will lose the easy auto-update and email notifications.
* `login_whitelist_ip[]` now supports hostnames so you can [whitelist](https://matomo.org/faq/how-to/faq_25543/) your IP addresses and/or Hostnames and keep your Matomo secure.

### Updated commands

* 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.

### New APIs

* 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` and `clearEcommerceCart` to allow better control over what is in the e-commerce cart.
* Tracking API requests now include `&consent=1` in the Tracking API URL When [consent](https://developer.matomo.org/guides/tracking-javascript-guide#asking-for-consent) has been given by a user.

### Breaking Changes
* Changed some menu items to use translation keys instead (see [PR #12885](https://github.com/matomo-org/matomo/pull/12885)).
* The methods `assertResponseCode()` and `assertHttpResponseText()` in `Piwik\Tests\Framework\TestCase\SystemTestCase` have been deprecated and will be removed in Matomo 4.0. Please use `Piwik\Http` instead.
* The classes `PHPUnit\Framework\Constraint\HttpResponseText` and `PHPUnit\Framework\Constraint\ResponseCode` have been deprecated and will be removed in Matomo 4.0. Please use `Piwik\Http` instead.
* Creating links through the Proxy has been deprecated. Use rel="nofollow" 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

## Matomo 3.5.1

### New APIs

* Added new method `Piwik\API\Request::isRootRequestApiRequest()` to detect if the root request is an API request.

## Matomo 3.5.0

### Breaking Changes

* Flattened action url reports now always include a leading `/` and will no longer include the `default_action_name`. e.g. `path/to/index` will now be `/path/to/`. This might affect configured custom alerts, as this plugin uses the flattened url reports for comparison.

### New APIs

* New JavaScript tracker functions to [ask for consent](https://developer.matomo.org/guides/tracking-javascript-guide#asking-for-consent): `requireConsent`, `rememberConsentGiven`, `setConsentGiven`, `forgetConsentGiven`.

### New Features
* New events `PrivacyManager.deleteLogsOlderThan`, `PrivacyManager.exportDataSubjects` and `PrivacyManager.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

## Matomo 3.4.0

### Breaking Changes
`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

### New APIs
* 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` and `resetDashboardLayout`
  * 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"](https://matomo.org/faq/how-to/faq_23654/) 

## Matomo 3.3.0

Piwik is now Matomo. Read more about this change in the [official announcement](https://matomo.org/blog/2018/01/piwik-is-now-matomo).

### New APIs

* New HTTP API `API.getMatomoVersion` was introduced. The previous HTTP API `API.getPiwikVersion` will still work but will now be hidden from the API reference page.

## Piwik 3.2.2

### Breaking Changes
* The `historyService` along with `broadcast.init`, `broadcast.propagateAjax`, `broadcast.pageLoad` have been deprecated and will be removed in Piwik 4. 


## Piwik 3.2.1

### New APIs

### New Features
 * 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` and `Live.filterProfileSummaries`
 * New JavaScript method `piwikHelper.registerShortcut` allows plugins to bind keyboard shortcuts. A summary for available shortcuts will be shown by pressing `?`

## Piwik 3.2.0

### New Segments
* 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` and `Live.filterVisitorDetails`

### New APIs
* 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 automatically
  * `Metric.filterMetrics` Triggered to filter metrics
* The following new API classes have been added:
 * `Piwik\Columns\MetricsList` Holds a list of all available metrics
 * `Piwik\Columns\ComputedMetricFactory` Can be used to create computed metrics
 * `Piwik\Columns\DimensionMetricFactory` Can be used to create metrics directly within a dimension

### New Features
* New config.ini.php setting `show_update_notification_to_superusers_only` makes it possible to hide update notifications for all users except of superusers

## Piwik 3.1.0

### Breaking Changes
* The event `Live.getAllVisitorDetails` has been deprecated and will be removed in Piwik 4. Use a `VisitorDetails` class instead (see Live plugin). 

### New Features
* New method `setSecureCookie` that sets the cookie's secure parameter

### New APIs
* 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

### New commands
* The commands `plugin:activate` and `plugin:deactivate` can now activate and deactivate multiple plugins at once

## Piwik 3.0.4

### New APIs
* 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` and `System.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`, and `getSessionCookieTimeout` have been added for better cookie support in plugins. 
* `email` and `url` form fields can now be used in settings.

## Piwik 3.0.3

### Breaking Changes
* 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 to `true`). If set to `false` it will also set `ViewDataTable\Config::$show_flatten_table` to `false`

### New APIs
* A new event `Controller.triggerAdminNotifications` has been added to let plugins know when they are supposed to trigger notifications in the admin.

### Library updates
* pChart library has been removed in favor of [CpChart](https://github.com/szymach/c-pchart), a pChart fork with composer support and PSR standards. 

## Piwik 3.0.2

### New Features
* A new SMS provider for sms reports has been added: [ASPSMS.com](https://www.aspsms.com/en/?REF=227830)

### New APIs
* 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

### Changes
* 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)

## Piwik 3.0.1

### New APIs
* 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](https://matomo.org/docs/user-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).

## Piwik 3.0.0

### New guide

Read more about migrating a plugin from Piwik 2.X to Piwik 3 in [our Migration guide](https://developer.matomo.org/guides/migrate-piwik-2-to-3).

### Breaking Changes
* When using the Piwik JavaScript Tracking via `_paq.push`, it is now required to configure the tracker (eg calling `setSiteId` and `setTrackerUrl`) before the `piwik.js` JavaScript tracker is loaded to ensure the tracker works correctly. 
If the tracker is not initialised correctly, the browser console will display the error "_paq.push() was used but Piwik tracker was not initialized before the piwik.js file was loaded. [...]" 
* The UserManager API methods do no longer return any `token_auth` properties when requesting a user
* The menu classes `Piwik\Menu\MenuReporting` and `Piwik\Menu\MenuMain` have been removed
* The class `Piwik\Plugin\Widgets` has been removed and replaced by `Piwik\Widget\Widget`. For each widget one class is needed from now on. You can generate a widget via `./console generate:widget`.
* The class `Piwik\WidgetList` class has been moved to `Piwik\Widget\WidgetsList`.
* The method `Piwik\Plugins\API\API::getLastDate()` has been removed.
* The method `Piwik\Archive::getDataTableFromArchive()` has been removed, use `Piwik\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()` and `Report::configureReportingMenu()` have been removed, use the new method `Report::configureWidgets()` instead.
* The method `Report::getCategory()` has been moved to `Report::getCategoryId()` and does no longer return the translated category but the translation key of the category.
* The property `Report::$category` has been renamed to `Report::$categoryId`
* The methods `Report::factory()`, `Report::getAllReportClasses()`, `Report::getAllReports` have been moved to the `Piwik\Plugin\Reports` class.
* The properties `Report::$widgetTitle`, `Report::$widgetParams` and `Report::$menuTitle` were removed, use the method `Report::configureWidgets()` to create widgets instead
* In the HTTP API methods `Dashboard.getDefaultDashboard` and `Dashboard.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 new `plugin:list`, `plugin:activate` and `plugin:deactivate` commands as announced in Piwik 2.11
* The visibility of private properties and methods in `Piwik\Plugins\Login\Controller` were changed to `protected`
* 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)` to `configureAdminMenu(MenuAdmin $menu)` in your `Menu.php`.
* The method `Piwik\Menu\MenuAbstract::add()` has been removed, use `Piwik\Menu\MenuAbstract::addItem()` instead
* The method `Piwik\Menu\MenuAdmin::addSettingsItem()` was removed, use  `Piwik\Menu\MenuAdmin::addSystemItem()` instead.
* A new method `Piwik\Menu\MenuAdmin::addMeasurablesItem()` was added.
* The class `Piwik\Plugin\Settings` has been split to `Piwik\Settings\Plugin\SystemSettings` and `Piwik\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()` see `Piwik\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](https://developer.matomo.org/guides/dimensions) instead of using `Tracker` events.
 * `Tracker.newVisitorInformation`
 * `Tracker.recordAction`
 * `Tracker.recordEcommerceGoal`
 * `Tracker.recordStandardGoals`
 * `API.getSegmentDimensionMetadata` Define segments in [Dimension](https://developer.matomo.org/guides/dimensions) instead
 * `Menu.Admin.addItems` Create a [Menu](https://developer.matomo.org/guides/menus) instead of using `Menu` events
 * `Menu.Reporting.addItems`
 * `Menu.Top.addItems`
 * `ViewDataTable.addViewDataTable` Create a [Visualization](https://developer.matomo.org/guides/visualizing-report-data) instead
 * `ViewDataTable.getDefaultType` Specify the default type in a [Report](https://developer.matomo.org/guides/custom-reports) instead
 * `Login.authenticate`  Create a custom SessionInitializer instead of using `Login` events
 * `Login.initSession.end`
 * `Login.authenticate.successful`
* When posting one of the events `API.Request.dispatch`, `API.Request.dispatch.end`, `API.$plugin.$apiAction`, or `API.$plugin.$apiAction.end` the `$finalParameters` parameter is indexed in Piwik 2 (eg `array(1, 6)`), and named in Piwik 3 (eg `array('idSite' => 1, 'idGoal' => 6)`)
* 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 list

   old module | old action | new module | new action
   ---------- | ---------- | ---------- | ----------
   UserSettings | getPlugin | DevicePlugins | getPlugin
   UserSettings | index | DevicesDetection | software
   UserSettings | getBrowser | DevicesDetection | getBrowsers
   UserSettings | getBrowserVersions | DevicesDetection | getBrowserVersions
   UserSettings | getMobileVsDesktop | DevicesDetection | getType
   UserSettings | getOS | DevicesDetection | getOsVersions
   UserSettings | getOSFamily | DevicesDetection | getOsFamilies
   UserSettings | getBrowserType | DevicesDetection | getBrowserEngines
   UserSettings | getResolution | Resolution | getResolution
   UserSettings | getConfiguration | Resolution | getConfiguration
   UserSettings | getLanguage | UserLanguage | getLanguage
   UserSettings | getLanguageCode | UserLanguage | getLanguageCode


Read more about migrating a plugin from Piwik 2.X to Piwik 3 on our [Migration guide](https://developer.matomo.org/guides/migrate-piwik-2-to-3).

### Deprecations
* The method `Piwik\Updates::getMigrationQueries()` has been deprecated and renamed to `getMigrations()`. It is still supported to use the method, but the method will be removed in Piwik 4.0.0
* The method `Piwik\Updater::executeMigrationQueries()` has been deprecated and renamed to `executeMigrations`. It is still supported to use the method, but the method will be removed in Piwik 4.0.0.

### New APIs
* Multiple widgets for one report can now be created via the `Report::configureWidgets()` method via the new classes `Piwik\Widget\ReportWidgetFactory` and `Piwik\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 method `Report::getSubCategory()` lets you get this value.
* The new classes `Piwik\Widget\Widget`, `Piwik\Widget\WidgetConfig` and `Piwik\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 visualizations
 * `Dimension.addDimension` lets you add custom dimensions
 * `Dimension.filterDimension` lets you filter any dimensions
 * `Report.addReports` lets you add dynamically created reports
 * `Report.filterReports` lets you filter any report
 * `Updater.componentUpdated` triggered after core or a plugin has been updated
 * `PluginManager.pluginInstalled` triggered after a plugin was installed
 * `PluginManager.pluginUninstalled` triggered after a plugin was uninstalled
 * `Updater.componentInstalled` triggered after a component was installed
 * `Updater.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](https://developer.matomo.org/api-reference/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 option `getJavascriptTag` to enable the tracking of users that have JavaScript disabled

### Changes
* 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

### New features
* 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.

### Library updates
* Updated AngularJS from 1.2.28 to 1.4.3
* Updated several backend libraries to their latest version: doctrine/cache, php-di.

### Internal change
* 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.

## Piwik 2.16.3

### New APIs
* 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'])`

### Internal Changes
* 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` to `expected-screenshots`. The UI-Test-Runner is now able to handle both names.

## Piwik 2.16.2

### New APIs
 * 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.](https://developer.matomo.org/guides/tracking-javascript-guide#multiple-piwik-trackers)
 * It is possible to get an asynchronously created tracker instance (`addTracker`) via the method `Piwik.getAsyncTracker(optionalPiwikUrl, optionalPiwikSiteId)`. This allows you to get the tracker instance and to send different tracking requests to this Piwik instance and to configure it differently than other tracker instances.
 * Added a new API method `Goals.getGoal($idSite, $idGoal)` to fetch a single goal.
 
### Internal change
 * Piwik is now compatible with PHP7. 
 * `piwik.js`, if you call the method `setDomains` note that that the behavior has slightly changed. The current page domain (hostname) will now be added automatically if none of the given host alias passed as a parameter to `setDomains` contain a path and if no host alias is already given for the current host alias. 
 Say you are on "example.org" and set `hostAlias = ['example.com', 'example.org/test']` then the current "example.org" domain will not be added as there is already a more restrictive hostAlias 'example.org/test' given. 
 We also do not add the current page domain (hostname) automatically if there was any other host specifying any path such as `['example.com', 'example2.com/test']`. 
 In this case we also do not add the current page domain "example.org" automatically as the "path" feature is used. As soon as someone uses the path feature, for Piwik JS Tracker to work correctly in all cases, one needs to specify all hosts manually. [Learn more.](http://developer.matomo.org/guides/tracking-javascript-guide#measuring-domains-andor-sub-domains)
 * `piwik.js`: after an e-commerce order is tracked using `trackEcommerceOrder`, the items in the cart will now be removed from the JavaScript object. Calling `trackEcommerceCartUpdate` will not remove the items in the cart.   


## Piwik 2.16.1

### New features
 * New method `setIsWritableByCurrentUser` for `SystemSetting` 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](http://developer.matomo.org/guides/tracking-javascript-guide#tracking-a-group-of-pages-in-a-separate-website)
 * 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 your `config.ini.php` file. By default, the following query string parameters will be removed: `gclid, fb_xd_fragment, fb_comment_id, phpsessid, jsessionid, sessionid, aspsessionid, doing_wp_cron, sid`.

### Deprecations
* The following PHP functions have been deprecated and will be removed in Piwik 3.0:
 * `SettingsServer::isApache()` 

### New guides
  * JavaScript Tracker: [Measuring domains and/or sub-domains](http://developer.matomo.org/guides/tracking-javascript-guide#measuring-domains-andor-sub-domains)
  
### Breaking Changes
 * 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.   
 
### Internal change
 * 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](http://developer.matomo.org/guides/tracking-javascript-guide#tracking-one-domain) when tracking one or several domains and/or paths.

## Piwik 2.16.1

### Internal change
 * 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.

## Piwik 2.16.0

### New features
 * New segment `actionType` lets you segment all actions of a given type, eg. `actionType==events` or `actionType==downloads`. Action types values are: `pageviews`, `contents`, `sitesearches`, `events`, `outlinks`, `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.](http://developer.matomo.org/api-reference/segmentation)
 * 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 domain `matomo.org` but to any other path than `website1/*` 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 the `core:archive` command. The given cli options will be forwarded to the actual PHP command. This allows to for example specify a different memory limit for the archiving process like this: `./console core:archive --php-cli-options="-d memory_limit=8G"`
 * 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 from `global.ini.php` in the UI, and whether they were overridden in your `config/config.ini.php`

### New commands
 * New command `config:set` lets you set INI config options from the command line. This command can be used for convenience or for automation.
   
### Internal changes
 * `UsersManager.*` API calls: when an API request specifies a `token_auth` of a user with `admin` permission, the returned dataset will not include all usernames as previously, API will now only return usernames for users with `view` or `admin` permission to website(s) viewable by this `token_auth`. 
 * 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 in `config/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](https://github.com/matomo-org/searchengine-and-social-list)).
 * In [UI screenshot tests](https://developer.matomo.org/guides/tests-ui), a test environment `configOverride` setting should be no longer overwritten. Instead new values should be added to the existing `configOverride` array in PHP or JavaScript. For example instead of `testEnvironment.configOverride = {group: {name: 1}}` use `testEnvironment.overrideConfig('group', 'name', '1')`.

### New APIs
 * Add your own SMS/Text provider by creating a new class in the `SMSProvider` directory of your plugin. The class has to extend `Piwik\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.

### Deprecations
 * The method `DB::tableExists` was un-used and has been removed.


## Piwik 2.15.0 

### New commands
 *  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](https://matomo.org/faq/how-to/faq_155/))

### New APIs and features
* Piwik 2.15.0 is now mostly compatible with PHP7. 
* The JavaScript Tracker `piwik.js` got a new method `logAllContentBlocksOnPage` to log all found content blocks within a page to the console. This is useful to debug / test content tracking. It can be triggered via `_paq.push(['logAllContentBlocksOnPage'])`
* 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 and `CronArchive.end` when the archiver ended.
* Piwik tracker can now be configured with strict Content Security Policy ([CSP FAQ](https://matomo.org/faq/general/faq_20904/)).
* Super Users can choose whether to use the latest stable release or latest Long Term Support release. 

### Breaking Changes
* The method `Dimension::getId()` has been set as `final`. 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 plugin `AnonymousPiwikUsageMeasurement`

### Deprecations
* 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](https://developer.matomo.org/guides/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.


### Internal changes
* 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](https://github.com/douglascrockford/JSON-js) with [JSON3](https://bestiejs.github.io/json3/) to implement CSP (Content Security Policy) as JSON3 does not use `eval()`. JSON3 will be used if a browser does not provide a native JSON API. We are using `JSON3` in a way that it will not conflict if your website is using `JSON3` as well.
* The option `branch` of the console command `development: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 of `1000000`)
* Database connections now use `UTF-8` charset explicitly to force UTF-8 data handling

## Piwik 2.14.0

### Breaking Changes
* The `UserSettings` API has been removed. The API was deprecated in earlier versions. Use `DevicesDetection`, `Resolution` and `DevicePlugins` API instead.
* Many translations have been moved to the new Intl plugin. Most of them will still work, but please update their usage. See https://github.com/matomo-org/matomo/pull/8101 for a full list 

### New features 
* The JavaScript Tracker does now track outlinks and downloads if a user opens the context menu if the `enabled` parameter of the `enableLinkTracking()` method is set to `true`. To use this new feature use `tracker.enableLinkTracking(true)` or `_paq.push(['enableLinkTracking', true]);`. This is not industry standard and is vulnerable to false positives since not every user will select "Open in a new tab" when the context menu is shown. Most users will do though and it will lead to more accurate results in most cases.
* 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).

### Commands updates
* 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 argument `task` that lets you force run a particular scheduled task.

### Library updates
* Updated pChart library from 2.1.3 to 2.1.4. The files were moved from the directory `libs/pChart2.1.3` to `libs/pChart`

### Internal change
* 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.

## Piwik 2.13.0

### Breaking Changes
* The API method `Live.getLastVisitsDetails` does no longer support the API parameter `filter_sort_column` to prevent possible memory issues when `filter_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 use `piwik.php` for checks please use `piwik.php?rec=0`.

### Deprecations
* The method `Piwik\Archive::getBlob()` has been deprecated and will be removed from June 1st 2015. Use one of the methods `getDataTable*()` methods instead.
* The API parameter `countVisitorsToFetch` of the API method `Live.getLastVisitsDetails` has been deprecated as `filter_offset` and `filter_limit` work correctly now.

### New commands
* 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.

### APIs Improvements
* Visitor details now additionally contain: `deviceTypeIcon`, `deviceBrand` and `deviceModel`
* In 2.6.0 we added the possibility to use `filter_limit` and `filter_offset` if an API returns an indexed array. This was not working in all cases and is fixed now. 
* The API parameter `filter_pattern` and `filter_offset[]` can now be used if an API returns an indexed array.

### Internal changes

* The referrer spam filter has moved from the `referrer_urls_spam` INI option (in `global.ini.php`) to a separate package (see [https://github.com/matomo-org/referrer-spam-list](https://github.com/matomo-org/referrer-spam-list)).

## Piwik 2.12.0

### Breaking Changes
* The deprecated method `Period::factory()` has been removed. Use `Period\Factory` instead.
* The deprecated method `Config::getConfigSuperUserForBackwardCompatibility()` has been removed.
* The deprecated methods `MenuAdmin::addEntry()` and `MenuAdmin::removeEntry()` have been removed. Use `Piwik\Plugin\Menu` instead.
* The deprecated methods `MenuTop::addEntry()` and `MenuTop::removeEntry()` have been removed. Use `Piwik\Plugin\Menu` instead.
* The deprecated method `SettingsPiwik::rewriteTmpPathWithInstanceId()` has been removed.
* The following deprecated methods from the `Piwik\IP` class have been removed, use `Piwik\Network\IP` instead:
  * `sanitizeIp()`
  * `sanitizeIpRange()`
  * `P2N()`
  * `N2P()`
  * `prettyPrint()`
  * `isIPv4()`
  * `long2ip()`
  * `isIPv6()`
  * `isMappedIPv4()`
  * `getIPv4FromMappedIPv6()`
  * `getIpsForRange()`
  * `isIpInRange()`
  * `getHostByAddr()`

### Deprecations
* `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()` and `update()` methods anymore. It is still supported to use those, but developers should instead override the `Updates::getMigrationQueries()` and `Updates::doUpdate()` instance methods.

### New features
* `API` classes can now use dependency injection in their constructor to inject other instances.

### New commands
* 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.

## Piwik 2.11.0

### Breaking Changes
* 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 as `Windows` with versions like `XP`, `7`, `8`, etc.
* Reporting for operating systems has been adjusted to report information according to browser information. Visitor details now contain: `operatingSystemName`, `operatingSystemIcon`, `operatingSystemCode` and `operatingSystemVersion`

### Deprecations
* The following methods have been deprecated in favor of the new `Piwik\Intl` component:
  * `Piwik\Common::getContinentsList()`: use `RegionDataProvider::getContinentList()` instead
  * `Piwik\Common::getCountriesList()`: use `RegionDataProvider::getCountryList()` instead
  * `Piwik\Common::getLanguagesList()`: use `LanguageDataProvider::getLanguageList()` instead
  * `Piwik\Common::getLanguageToCountryList()`: use `LanguageDataProvider::getLanguageToCountryList()` instead
  * `Piwik\Metrics\Formatter::getCurrencyList()`: use `CurrencyDataProvider::getCurrencyList()` instead
* The `Piwik\Translate` class has been deprecated in favor of `Piwik\Translation\Translator`.
* The `core:plugin` console has been deprecated in favor of the new `plugin:list`, `plugin:activate` and `plugin:deactivate` commands
* The following classes have been deprecated:
  * `Piwik\TaskScheduler`: use `Piwik\Scheduler\Scheduler` instead
  * `Piwik\ScheduledTask`: use `Piwik\Scheduler\Task` instead
* The API method `UserSettings.getLanguage` is deprecated and will be removed from May 1st 2015. Use `UserLanguage.getLanguage` instead
* The API method `UserSettings.getLanguageCode` is deprecated and will be removed from May 1st 2015. Use `UserLanguage.getLanguageCode` instead
* The `Piwik\Registry` class has been deprecated in favor of using the container:
  * `Registry::get('auth')` should be replaced with `StaticContainer::get('Piwik\Auth')`
  * `Registry::set('auth', $auth)` should be replaced with `StaticContainer::getContainer()->set('Piwik\Auth', $auth)`
 
### New features
* 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.

### New commands
* 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](https://github.com/matomo-org/matomo/issues/6436)

### Library updates
* Updated AngularJS from 1.2.26 to 1.2.28
* Updated piwik/device-detector from 2.8 to 3.0

### Internal change
* UI specs were moved from `tests/PHPUnit/UI` to `tests/UI`. We also moved the UI specs directly into the Piwik repository meaning the [piwik-ui-tests](https://github.com/matomo-org/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.

## Piwik 2.10.0

### Breaking Changes
* API responses containing visitor information will no longer contain the fields `screenType` and `screenTypeIcon` 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.](http://developer.matomo.org/guides/logging)
* 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` and `log_only_when_debug_parameter` have been removed

### Library updates
* We added the `symfony/var-dumper` library allowing you to better print any arbitrary PHP variable via `dump($var1, $var2, ...)`.
* Piwik now uses [Monolog](https://github.com/Seldaek/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](https://github.com/matomo-org/tracker-proxy).

### Deprecations
* 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. Use `DevicesDetection.getBrowserVersions` instead
* The API method `UserSettings.getBrowser` is deprecated and will be removed from May 1st 2015. Use `DevicesDetection.getBrowsers` instead
* The API method `UserSettings.getOSFamily` is deprecated and will be removed from May 1st 2015. Use `DevicesDetection.getOsFamilies` instead
* The API method `UserSettings.getOS` is deprecated and will be removed from May 1st 2015. Use `DevicesDetection.getOsVersions` instead
* The API method `UserSettings.getMobileVsDesktop` is deprecated and will be removed from May 1st 2015. Use `DevicesDetection.getType` instead
* The API method `UserSettings.getBrowserType` is deprecated and will be removed from May 1st 2015. Use `DevicesDetection.getBrowserEngines` instead
* The API method `UserSettings.getResolution` is deprecated and will be removed from May 1st 2015. Use `Resolution.getResolution` instead
* The API method `UserSettings.getConfiguration` is deprecated and will be removed from May 1st 2015. Use `Resolution.getConfiguration` instead
* The API method `UserSettings.getPlugin` is deprecated and will be removed from May 1st 2015. Use `DevicePlugins.getPlugin` instead
* The API method `UserSettings.getWideScreen` has been removed. Use `UserSettings.getScreenType` instead.
* `Piwik\SettingsPiwik::rewriteTmpPathWithInstanceId()` has been deprecated. Instead of hardcoding the `tmp/` path everywhere in the codebase and then calling `rewriteTmpPathWithInstanceId()`, developers should get the `path.tmp` configuration value from the DI container (e.g. `StaticContainer::getContainer()->get('path.tmp')`).
* The method `Piwik\Log::setLogLevel()` has been deprecated
* The method `Piwik\Log::getLogLevel()` has been deprecated

## Piwik 2.9.1

### Breaking Changes
* The HTTP Tracker API does now respond with a HTTP 400 instead of a HTTP 500 in case an invalid `idsite` is used

### New APIs
* New URL parameter `send_image=0` in the [HTTP Tracking API](http://developer.matomo.org/api-reference/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).

### New commands
* `core:plugin list` lists all plugins currently activated in Piwik.

## Piwik 2.9.0

### Breaking Changes
* Development related [console commands](http://developer.matomo.org/guides/piwik-on-the-command-line) 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.

### Deprecations
* Most methods of `Piwik\IP` have been deprecated in favor of the new [piwik/network](https://github.com/matomo-org/component-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 in `config/global.ini.php`

### Library updates
* Code for manipulating IP addresses has been moved to a separate standalone component: [piwik/network](https://github.com/matomo-org/component-network). Backward compatibility is kept in Piwik core.

## Piwik 2.8.2

### Library updates
* Updated AngularJS from 1.2.25 to 1.2.26
* Updated jQuery from 1.11.0 to 1.11.1

## Piwik 2.8.0

### Breaking Changes
* 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](http://developer.matomo.org/2.x/api-reference/Piwik/Auth) to learn more.**
* The `Piwik\Unzip\*` classes have been extracted out of the Piwik repository into a separate component named [Decompress](https://github.com/matomo-org/component-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 the `Piwik\Decompress\*` namespace (inside the new repository).
  * `Piwik\Unzip\UncompressInterface` has been moved and renamed to `Piwik\Decompress\DecompressInterface` (inside the new repository).

### Deprecations
* 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.

### New API Features
* The pivotBy and related query parameters can be used to pivot reports by another dimension. Read more about the new query parameters [here](http://developer.matomo.org/api-reference/reporting-api#optional-api-parameters).

### Library updates
* Updated AngularJS from 1.2.13 to 1.2.25

### New commands
* `generate:angular-directive` lets you easily generate a template for a new angular directive for any plugin.

### Internal change
* 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. 

## Piwik 2.7.0

### Reporting APIs
* Several APIs will now expose a new metric `nb_users` which measures the number of unique users when a [User ID](http://matomo.org/docs/user-id/) is set.
* New APIs have been added for [Content Tracking](https://matomo.org/docs/content-tracking/) feature: Contents.getContentNames, Contents.getContentPieces

### Deprecations
* The `Piwik\Menu\MenuAbstract::add()` method is deprecated in favor of `addItem()`. Read more about this here: [#6140](https://github.com/matomo-org/matomo/issues/6140). We do not plan to remove the deprecated method before Piwik 3.0.

### New APIs
* It is now easier to generate the URL for a menu item see [#6140](https://github.com/matomo-org/matomo/issues/6140), [urlForDefaultAction()](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Menu#urlfordefaultaction), [urlForAction()](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Menu#urlforaction), [urlForModuleAction()](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Menu#urlformoduleaction)

### New commands
* `core:clear-caches` Lets you easily delete all caches. This command can be useful for instance after updating Piwik files manually.


## Piwik 2.6.0

### Deprecations
* 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.

#### Reporting API
* If an API returns an indexed array, it is now possible to use `filter_limit` and `filter_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` or `getVisitorProfile`. If all core plugins are enabled as by default there will be no change at all except the order of the properties within one visitor.

### New commands
* `core:run-scheduled-tasks` lets you run all scheduled tasks due to run at this time. Useful for instance when testing tasks.

#### Internal change
 * 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 run `php composer.phar self-update && php composer.phar install` to make your Piwik work again. Also make sure to no longer include `core/Loader.php` in case it is used in any custom script.
 * 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.*` or `Request.initAuthenticationObject` event or it has to define dimensions in order to be detected as a tracker plugin.

## Piwik 2.5.0

### Breaking Changes
* 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 call `storeCustomVariablesInCookie` before the first call to `trackPageView`. Read more about [Javascript Tracking here](http://developer.matomo.org/api-reference/tracking-javascript).
* The [settings](http://developer.matomo.org/guides/piwik-configuration) API will receive the actual entered value and will no longer convert characters like `&` to `&amp;`. If you still want this behavior - for instance to prevent XSS - you can define a filter by setting the `transform` property like this:
  `$setting->transform = function ($value) { return Common::sanitizeInputValue($value); }`
* Config setting `disable_merged_assets` moved from `Debug` section to `Development`. The updater will automatically change the section for you.
* `API.getRowEvolution` will throw an exception if a report is requested that does not have a dimension, for instance `VisitsSummary.get`. This is a fix as an invalid format was returned before see [#5951](https://github.com/matomo-org/matomo/issues/5951)
* `MultiSites.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](https://github.com/matomo-org/matomo/issues/5987)

### Deprecations
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](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Report) class instead to define new reports. There is an updated guide as well [Part1](http://developer.matomo.org/guides/getting-started-part-1)
* `WidgetsList.addWidgets`: use [Widgets](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Widgets) class instead to define new widgets
* `Menu.Admin.addItems`, `Menu.Reporting.addItems`, `Menu.Top.addItems`: use [Menu](http://developer.matomo.org/api-reference/Piwik/Plugin/Menu) class instead
* `TaskScheduler.getScheduledTasks`: use [Tasks](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Tasks) class instead to define new tasks
* `Tracker.recordEcommerceGoal`, `Tracker.recordStandardGoals`, `Tracker.newConversionInformation`: use [Conversion Dimension](http://developer.matomo.org/api-reference/Piwik/Plugin/Dimension/ConversionDimension) class instead
* `Tracker.existingVisitInformation`, `Tracker.newVisitorInformation`, `Tracker.getVisitFieldsToPersist`: use [Visit Dimension](http://developer.matomo.org/api-reference/Piwik/Plugin/Dimension/VisitDimension) class instead
* `ViewDataTable.addViewDataTable`: This event is no longer needed. Visualizations are automatically discovered if they are placed within a `Visualizations` directory inside the plugin.

### New features

#### Translation search
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](http://developer.matomo.org/guides/internationalization) here.

#### Reporting API
It is now possible to use the `filter_sort_column` parameter when requesting `Live.getLastVisitDetails`. For instance `&filter_sort_column=visitCount`. 

#### @since annotation
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](http://developer.matomo.org/api-reference/classes). 

### New APIs
* [Report](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Report) to add a new report
* [Action Dimension](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Dimension/ActionDimension) to add a dimension that tracks action related information
* [Visit Dimension](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Dimension/VisitDimension) to add a dimension that tracks visit related information
* [Conversion Dimension](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Dimension/ConversionDimension) to add a dimension that tracks conversion related information
* [Dimension](http://developer.matomo.org/2.x/api-reference/Piwik/Columns/Dimension) to add a basic non tracking dimension that can be used in `Reports`
* [Widgets](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/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](http://developer.matomo.org/2.x/api-reference/Piwik/Menu/MenuAdmin) to add or modify admin menu items. 
  * [MenuReporting](http://developer.matomo.org/2.x/api-reference/Piwik/Menu/MenuReporting) to add or modify reporting menu items
  * [MenuUser](http://developer.matomo.org/2.x/api-reference/Piwik/Menu/MenuUser) to add or modify user menu items
* [Tasks](http://developer.matomo.org/2.x/api-reference/Piwik/Plugin/Tasks) to add scheduled tasks

### New commands
* `generate:theme` lets you easily generate a new theme and customize colors, see the [Theming guide](http://developer.matomo.org/guides/theming)
* `generate:update` lets you generate an update file
* `generate:report` lets you generate a report
* `generate:dimension` lets you enhance the tracking by adding new dimensions
* `generate:menu` lets you generate a menu class to add or modify menu items
* `generate:widgets` lets you generate a widgets class to add or modify widgets
* `generate:tasks` lets you generate a tasks class to add or modify tasks
* `development: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 

<!--
## Template: Matomo version number

### Breaking Changes
### Deprecations
### API Changes
### New features
### New APIs
### New commands
### New guides
### Library updates
### Internal change
 -->

Find the general Matomo Changelogs for each release at [matomo.org/changelog](https://matomo.org/changelog/)