PHP Class Piwik\Plugins\SitesManager\API

This API lets you create websites via "addSite", update existing websites via "updateSite" and delete websites via "deleteSite". When creating websites, it can be useful to access internal codes used by Piwik for currencies via "getCurrencyList", or timezones via "getTimezonesList". There are also many ways to request a list of websites: from the website ID via "getSiteFromId" or the site URL via "getSitesIdFromSiteUrl". Often, the most useful technique is to list all websites that are known to a current user, based on the token_auth, via "getSitesWithAdminAccess", "getSitesWithViewAccess" or "getSitesWithAtLeastViewAccess" (which returns both). Some methods will affect all websites globally: "setGlobalExcludedIps" will set the list of IPs to be excluded on all websites, "setGlobalExcludedQueryParameters" will set the list of URL parameters to remove from URLs for all websites. The existing values can be fetched via "getExcludedIpsGlobal" and "getExcludedQueryParametersGlobal". See also the documentation about Managing Websites in Piwik.
Inheritance: extends Piwik\Plugin\API
Datei anzeigen Open project: piwik/piwik Class Usage Examples

Public Methods

Method Description
__construct ( SettingsProvider $provider, SettingsMetadata $settingsMetadata )
addSite ( string $siteName, array | string $urls = null, integer $ecommerce = null, null $siteSearch = null, string $searchKeywordParameters = null, string $searchCategoryParameters = null, string $excludedIps = null, null $excludedQueryParameters = null, string $timezone = null, string $currency = null, string $group = null, string $startDate = null, null | string $excludedUserAgents = null, integer $keepURLFragments = null, string $type = null, array | null $settingValues = null, boolean | null $excludeUnknownUrls = null ) : integer Add a website.
addSiteAliasUrls ( integer $idSite, array | string $urls ) : integer Add a list of alias Urls to the given idSite
deleteSite ( integer $idSite ) Delete a website from the database, given its Id. The method deletes the actual site as well as some associated data. However, it does not delete any logs or archives that belong to this website. You can delete logs and archives for a site manually as described in this FAQ: http://piwik.org/faq/how-to/faq_73/ .
getAllSites ( ) : array Returns all websites, requires Super User access
getAllSitesId ( ) : array Returns the list of all the website IDs registered.
getCurrencyList ( ) : array Returns the list of supported currencies
getCurrencySymbols ( ) : array( Returns the list of currency symbols
getDefaultCurrency ( ) : string Returns the default currency that will be set when creating a website through the API.
getDefaultTimezone ( ) : string Returns the default timezone that will be set when creating a website through the API.
getExcludedIpsGlobal ( ) : string Returns the list of IPs that are excluded from all websites
getExcludedQueryParametersGlobal ( ) : string Returns the list of URL query parameters that are excluded from all websites
getExcludedUserAgentsGlobal ( ) : string Returns the list of user agent substrings to look for when excluding visits for all websites. If a visitor's user agent string contains one of these substrings, their visits will not be included.
getImageTrackingCode ( integer $idSite, string $piwikUrl = '', $actionName = false, integer $idGoal = false, integer $revenue = false ) : string Returns image link tracking code for a given site with specified options.
getIpsForRange ( string $ipRange ) : array | false Get the start and end IP addresses for an IP address range
getJavascriptTag ( integer $idSite, string $piwikUrl = '', boolean $mergeSubdomains = false, boolean $groupPageTitlesByDomain = false, boolean $mergeAliasUrls = false, boolean $visitorCustomVariables = false, boolean $pageCustomVariables = false, boolean $customCampaignNameQueryParam = false, boolean $customCampaignKeywordParam = false, boolean $doNotTrack = false, boolean $disableCookies = false, boolean $trackNoScript = false ) : string Returns the javascript tag for the given idSite.
getKeepURLFragmentsGlobal ( ) : boolean Returns true if the default behavior is to keep URL fragments when tracking, false if otherwise.
getNumWebsitesToDisplayPerPage ( ) : integer Returns the number of websites to display per page.
getPatternMatchSites ( string $pattern, integer | false $limit = false ) : array Find websites matching the given pattern.
getSearchCategoryParametersGlobal ( ) : string
getSearchKeywordParametersGlobal ( ) : string
getSiteFromId ( integer $idSite ) : array Returns the website information : name, main_url
getSiteSettings ( $idSite )
getSiteUrlsFromId ( integer $idSite ) : array Returns the list of all URLs registered for the given idSite (main_url + alias URLs).
getSitesFromGroup ( string $group = '' ) : array Returns all websites belonging to the specified group
getSitesGroups ( ) : array Returns the list of website groups, including the empty group if no group were specified for some websites
getSitesIdFromSiteUrl ( string $url ) : array Returns the list of websites ID associated with a URL.
getSitesIdFromTimezones ( array $timezones ) : array Returns all websites with a timezone matching one the specified timezones
getSitesIdWithAdminAccess ( ) : array Returns the list of websites ID with the 'admin' access for the current user.
getSitesIdWithAtLeastViewAccess ( boolean $_restrictSitesToLogin = false ) : array Returns the list of websites ID with the 'view' or 'admin' access for the current user.
getSitesIdWithViewAccess ( ) : array Returns the list of websites ID with the 'view' access for the current user.
getSitesIdWithVisits ( boolean | integer $timestamp = false ) : array Returns the list of the website IDs that received some visits since the specified timestamp.
getSitesWithAdminAccess ( boolean $fetchAliasUrls = false, false | string $pattern = false, false | integer $limit = false ) : array Returns the list of websites with the 'admin' access for the current user.
getSitesWithAtLeastViewAccess ( boolean | integer $limit = false, boolean $_restrictSitesToLogin = false ) : array Returns the list of websites with the 'view' or 'admin' access for the current user.
getSitesWithViewAccess ( ) : array Returns the list of websites with the 'view' access for the current user.
getTimezonesList ( ) : array Returns the list of timezones supported.
getUniqueSiteTimezones ( ) : array Returns the list of unique timezones from all configured sites.
isSiteSpecificUserAgentExcludeEnabled ( ) : boolean Returns true if site-specific user agent exclusion has been enabled. If it hasn't, only the global user agent substrings (see @setGlobalExcludedUserAgents) will be used.
isTimezoneSupportEnabled ( ) : boolean Return true if Timezone support is enabled on server
renameGroup ( $oldGroupName, $newGroupName )
setDefaultCurrency ( string $defaultCurrency ) : boolean Sets the default currency that will be used when creating websites
setDefaultTimezone ( string $defaultTimezone ) : boolean Sets the default timezone that will be used when creating websites
setGlobalExcludedIps ( string $excludedIps ) : boolean Sets IPs to be excluded from all websites. IPs can contain wildcards.
setGlobalExcludedQueryParameters ( string $excludedQueryParameters ) : boolean Sets list of URL query parameters to be excluded on all websites.
setGlobalExcludedUserAgents ( string $excludedUserAgents ) Sets list of user agent substrings to look for when excluding visits. For more info,
setGlobalSearchParameters ( $searchKeywordParameters, $searchCategoryParameters ) : boolean Sets Site Search keyword/category parameter names, to be used on websites which have not specified these values Expects Comma separated list of query params names
setKeepURLFragmentsGlobal ( $enabled ) Sets whether the default behavior should be to keep URL fragments when tracking or not.
setSiteAliasUrls ( $idSite, $urls = [] ) : integer Set the list of alias Urls for the given idSite
setSiteSpecificUserAgentExcludeEnabled ( boolean $enabled ) Sets whether it should be allowed to exclude different user agents for different websites.
updateSite ( integer $idSite, string $siteName = null, string | array $urls = null, integer $ecommerce = null, null | integer $siteSearch = null, string $searchKeywordParameters = null, string $searchCategoryParameters = null, string $excludedIps = null, null | string $excludedQueryParameters = null, string $timezone = null, string $currency = null, string $group = null, string $startDate = null, null | string $excludedUserAgents = null, integer | null $keepURLFragments = null, string $type = null, array | null $settingValues = null, boolean | null $excludeUnknownUrls = null ) : boolean Update an existing website.
updateSiteCreatedTime ( $idSites, Date $minDate ) Updates the field ts_created for the specified websites.

Protected Methods

Method Description
getNormalizedUrls ( $url )

Private Methods

Method Description
checkAndReturnCommaSeparatedStringList ( $parameters )
checkAndReturnExcludedIps ( string $excludedIps ) : array Checks that the submitted IPs (comma separated list) are valid Returns the cleaned up IPs
checkAndReturnType ( $type )
checkName ( $siteName ) Check that the website name has a correct format.
checkValidCurrency ( $currency )
checkValidTimezone ( $timezone )
getModel ( )
getSitesFromIds ( array $idSites, boolean $limit = false ) : array Returns the list of websites from the ID array in parameters.
getSitesId ( )
getTimezonesListUTCOffsets ( )
isValidIp ( string $ip ) : boolean Tests if the IP is a valid IP, allowing wildcards, except in the first octet.
isValidUrl ( string $url ) : boolean Tests if the URL is a valid URL
postUpdateWebsite ( $idSite )
removeTrailingSlash ( string $url ) : string Remove the final slash in the URLs if found
saveMeasurableSettings ( $idSite, $idType, $settingValues )
setAndValidateMeasurableSettings ( $idSite, $idType, $settingValues )
setSettingValue ( $fieldName, $value, $settingValues )

Method Details

__construct() public method

public __construct ( SettingsProvider $provider, SettingsMetadata $settingsMetadata )
$provider Piwik\Plugin\SettingsProvider
$settingsMetadata Piwik\Plugins\CorePluginsAdmin\SettingsMetadata

addSite() public method

Requires Super User access. The website is defined by a name and an array of URLs.
public addSite ( string $siteName, array | string $urls = null, integer $ecommerce = null, null $siteSearch = null, string $searchKeywordParameters = null, string $searchCategoryParameters = null, string $excludedIps = null, null $excludedQueryParameters = null, string $timezone = null, string $currency = null, string $group = null, string $startDate = null, null | string $excludedUserAgents = null, integer $keepURLFragments = null, string $type = null, array | null $settingValues = null, boolean | null $excludeUnknownUrls = null ) : integer
$siteName string Site name
$urls array | string The URLs array must contain at least one URL called the 'main_url' ; if several URLs are provided in the array, they will be recorded as Alias URLs for this website. When calling API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
$ecommerce integer Is Ecommerce Reporting enabled for this website?
$siteSearch null
$searchKeywordParameters string Comma separated list of search keyword parameter names
$searchCategoryParameters string Comma separated list of search category parameter names
$excludedIps string Comma separated list of IPs to exclude from the reports (allows wildcards)
$excludedQueryParameters null
$timezone string Timezone string, eg. 'Europe/London'
$currency string Currency, eg. 'EUR'
$group string Website group identifier
$startDate string Date at which the statistics for this website will start. Defaults to today's date in YYYY-MM-DD format
$excludedUserAgents null | string
$keepURLFragments integer If 1, URL fragments will be kept when tracking. If 2, they will be removed. If 0, the default global behavior will be used.
$type string The website type, defaults to "website" if not set.
$settingValues array | null JSON serialized settings eg {settingName: settingValue, ...}
$excludeUnknownUrls boolean | null Track only URL matching one of website URLs
return integer the website ID created

addSiteAliasUrls() public method

If some URLs given in parameter are already recorded as alias URLs for this website, they won't be duplicated. The 'main_url' of the website won't be affected by this method.
public addSiteAliasUrls ( integer $idSite, array | string $urls ) : integer
$idSite integer
$urls array | string When calling API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
return integer the number of inserted URLs

deleteSite() public method

Requires Super User access.
public deleteSite ( integer $idSite )
$idSite integer

getAllSites() public method

Returns all websites, requires Super User access
public getAllSites ( ) : array
return array The list of websites, indexed by idsite

getAllSitesId() public method

Requires Super User access.
public getAllSitesId ( ) : array
return array The list of website IDs

getCurrencyList() public method

Returns the list of supported currencies
See also: getCurrencySymbols()
public getCurrencyList ( ) : array
return array ( currencyId => currencyName)

getCurrencySymbols() public method

Returns the list of currency symbols
See also: getCurrencyList()
public getCurrencySymbols ( ) : array(
return array(

getDefaultCurrency() public method

Returns the default currency that will be set when creating a website through the API.
public getDefaultCurrency ( ) : string
return string Currency ID eg. 'USD'

getDefaultTimezone() public method

Via the UI, if the default timezone is not UTC, it will be pre-selected in the drop down
public getDefaultTimezone ( ) : string
return string Timezone eg. UTC+7 or Europe/Paris

getExcludedIpsGlobal() public method

Returns the list of IPs that are excluded from all websites
public getExcludedIpsGlobal ( ) : string
return string Comma separated list of IPs

getExcludedQueryParametersGlobal() public method

Returns the list of URL query parameters that are excluded from all websites
public getExcludedQueryParametersGlobal ( ) : string
return string Comma separated list of URL parameters

getExcludedUserAgentsGlobal() public method

Returns the list of user agent substrings to look for when excluding visits for all websites. If a visitor's user agent string contains one of these substrings, their visits will not be included.
public getExcludedUserAgentsGlobal ( ) : string
return string Comma separated list of strings.

getImageTrackingCode() public method

Returns image link tracking code for a given site with specified options.
public getImageTrackingCode ( integer $idSite, string $piwikUrl = '', $actionName = false, integer $idGoal = false, integer $revenue = false ) : string
$idSite integer The ID to generate tracking code for.
$piwikUrl string The domain and URL path to the Piwik installation.
$idGoal integer An ID for a goal to trigger a conversion for.
$revenue integer The revenue of the goal conversion. Only used if $idGoal is supplied.
return string The HTML tracking code.

getIpsForRange() public method

Get the start and end IP addresses for an IP address range
public getIpsForRange ( string $ipRange ) : array | false
$ipRange string IP address range in presentation format
return array | false Array( low, high ) IP addresses in presentation format; or false if error

getJavascriptTag() public method

This tag must be included on every page to be tracked by Piwik
public getJavascriptTag ( integer $idSite, string $piwikUrl = '', boolean $mergeSubdomains = false, boolean $groupPageTitlesByDomain = false, boolean $mergeAliasUrls = false, boolean $visitorCustomVariables = false, boolean $pageCustomVariables = false, boolean $customCampaignNameQueryParam = false, boolean $customCampaignKeywordParam = false, boolean $doNotTrack = false, boolean $disableCookies = false, boolean $trackNoScript = false ) : string
$idSite integer
$piwikUrl string
$mergeSubdomains boolean
$groupPageTitlesByDomain boolean
$mergeAliasUrls boolean
$visitorCustomVariables boolean
$pageCustomVariables boolean
$customCampaignNameQueryParam boolean
$customCampaignKeywordParam boolean
$doNotTrack boolean
$disableCookies boolean
$trackNoScript boolean
return string The Javascript tag ready to be included on the HTML pages

getKeepURLFragmentsGlobal() public method

Returns true if the default behavior is to keep URL fragments when tracking, false if otherwise.

getNormalizedUrls() protected method

protected getNormalizedUrls ( $url )

getNumWebsitesToDisplayPerPage() public method

For example this is used in the All Websites Dashboard, in the Website Selector etc. If multiple websites are shown somewhere, one should request this method to detect how many websites should be shown per page when using paging. To use paging is always recommended since some installations have thousands of websites.

getPatternMatchSites() public method

Any website will be returned that matches the pattern in the name, URL or group. To limit the number of returned sites you can either specify filter_limit as usual or limit which is faster.
public getPatternMatchSites ( string $pattern, integer | false $limit = false ) : array
$pattern string
$limit integer | false
return array

getSearchCategoryParametersGlobal() public method

public getSearchCategoryParametersGlobal ( ) : string
return string Comma separated list of URL parameters

getSearchKeywordParametersGlobal() public method

public getSearchKeywordParametersGlobal ( ) : string
return string Comma separated list of URL parameters

getSiteFromId() public method

Returns the website information : name, main_url
public getSiteFromId ( integer $idSite ) : array
$idSite integer
return array

getSiteSettings() public method

public getSiteSettings ( $idSite )

getSiteUrlsFromId() public method

Returns the list of all URLs registered for the given idSite (main_url + alias URLs).
public getSiteUrlsFromId ( integer $idSite ) : array
$idSite integer
return array list of URLs

getSitesFromGroup() public method

Returns all websites belonging to the specified group
public getSitesFromGroup ( string $group = '' ) : array
$group string Group name
return array of sites

getSitesGroups() public method

Returns the list of website groups, including the empty group if no group were specified for some websites
public getSitesGroups ( ) : array
return array of group names strings

getSitesIdFromSiteUrl() public method

Returns the list of websites ID associated with a URL.
public getSitesIdFromSiteUrl ( string $url ) : array
$url string
return array list of websites ID

getSitesIdFromTimezones() public method

Returns all websites with a timezone matching one the specified timezones
public getSitesIdFromTimezones ( array $timezones ) : array
$timezones array
return array

getSitesIdWithAdminAccess() public method

For the superUser it returns all the websites in the database.
public getSitesIdWithAdminAccess ( ) : array
return array list of websites ID

getSitesIdWithAtLeastViewAccess() public method

For the superUser it returns all the websites in the database.
public getSitesIdWithAtLeastViewAccess ( boolean $_restrictSitesToLogin = false ) : array
$_restrictSitesToLogin boolean
return array list of websites ID

getSitesIdWithViewAccess() public method

For the superUser it doesn't return any result because the superUser has admin access on all the websites (use getSitesIdWithAtLeastViewAccess() instead).
public getSitesIdWithViewAccess ( ) : array
return array list of websites ID

getSitesIdWithVisits() public method

Requires Super User access.
Deprecation: since 2.15 This method will be removed in Piwik 3.0, there is no replacement.
public getSitesIdWithVisits ( boolean | integer $timestamp = false ) : array
$timestamp boolean | integer
return array The list of website IDs

getSitesWithAdminAccess() public method

For the superUser it returns all the websites in the database.
public getSitesWithAdminAccess ( boolean $fetchAliasUrls = false, false | string $pattern = false, false | integer $limit = false ) : array
$fetchAliasUrls boolean
$pattern false | string
$limit false | integer
return array for each site, an array of information (idsite, name, main_url, etc.)

getSitesWithAtLeastViewAccess() public method

For the superUser it returns all the websites in the database.
public getSitesWithAtLeastViewAccess ( boolean | integer $limit = false, boolean $_restrictSitesToLogin = false ) : array
$limit boolean | integer Specify max number of sites to return
$_restrictSitesToLogin boolean Hack necessary when running scheduled tasks, where "Super User" is forced, but sometimes not desired, see #3017
return array array for each site, an array of information (idsite, name, main_url, etc.)

getSitesWithViewAccess() public method

For the superUser it doesn't return any result because the superUser has admin access on all the websites (use getSitesWithAtLeastViewAccess() instead).
public getSitesWithViewAccess ( ) : array
return array for each site, an array of information (idsite, name, main_url, etc.)

getTimezonesList() public method

Used for addSite and updateSite
public getTimezonesList ( ) : array
return array of timezone strings

getUniqueSiteTimezones() public method

Returns the list of unique timezones from all configured sites.
public getUniqueSiteTimezones ( ) : array
return array ( string )

isSiteSpecificUserAgentExcludeEnabled() public method

Returns true if site-specific user agent exclusion has been enabled. If it hasn't, only the global user agent substrings (see @setGlobalExcludedUserAgents) will be used.

isTimezoneSupportEnabled() public method

Return true if Timezone support is enabled on server

renameGroup() public method

public renameGroup ( $oldGroupName, $newGroupName )

setDefaultCurrency() public method

Sets the default currency that will be used when creating websites
public setDefaultCurrency ( string $defaultCurrency ) : boolean
$defaultCurrency string Currency code, eg. 'USD'
return boolean

setDefaultTimezone() public method

Sets the default timezone that will be used when creating websites
public setDefaultTimezone ( string $defaultTimezone ) : boolean
$defaultTimezone string Timezone string eg. Europe/Paris or UTC+8
return boolean

setGlobalExcludedIps() public method

Will also apply to websites created in the future.
public setGlobalExcludedIps ( string $excludedIps ) : boolean
$excludedIps string Comma separated list of IPs to exclude from being tracked (allows wildcards)
return boolean

setGlobalExcludedQueryParameters() public method

Will also apply to websites created in the future.
public setGlobalExcludedQueryParameters ( string $excludedQueryParameters ) : boolean
$excludedQueryParameters string Comma separated list of URL query parameters to exclude from URLs
return boolean

setGlobalExcludedUserAgents() public method

Sets list of user agent substrings to look for when excluding visits. For more info,
public setGlobalExcludedUserAgents ( string $excludedUserAgents )
$excludedUserAgents string Comma separated list of strings. Each element is trimmed, and empty strings are removed.

setGlobalSearchParameters() public method

Sets Site Search keyword/category parameter names, to be used on websites which have not specified these values Expects Comma separated list of query params names
public setGlobalSearchParameters ( $searchKeywordParameters, $searchCategoryParameters ) : boolean
return boolean

setKeepURLFragmentsGlobal() public method

Sets whether the default behavior should be to keep URL fragments when tracking or not.
public setKeepURLFragmentsGlobal ( $enabled )
$enabled bool If true, the default behavior will be to keep URL fragments when tracking. If false, the default behavior will be to remove them.

setSiteAliasUrls() public method

Completely overwrites the current list of URLs with the provided list. The 'main_url' of the website won't be affected by this method.
public setSiteAliasUrls ( $idSite, $urls = [] ) : integer
return integer the number of inserted URLs

setSiteSpecificUserAgentExcludeEnabled() public method

Sets whether it should be allowed to exclude different user agents for different websites.

updateSite() public method

If only one URL is specified then only the main url will be updated. If several URLs are specified, both the main URL and the alias URLs will be updated.
public updateSite ( integer $idSite, string $siteName = null, string | array $urls = null, integer $ecommerce = null, null | integer $siteSearch = null, string $searchKeywordParameters = null, string $searchCategoryParameters = null, string $excludedIps = null, null | string $excludedQueryParameters = null, string $timezone = null, string $currency = null, string $group = null, string $startDate = null, null | string $excludedUserAgents = null, integer | null $keepURLFragments = null, string $type = null, array | null $settingValues = null, boolean | null $excludeUnknownUrls = null ) : boolean
$idSite integer website ID defining the website to edit
$siteName string website name
$urls string | array the website URLs When calling API via HTTP specify multiple URLs via `&urls[]=http...&urls[]=http...`.
$ecommerce integer Whether Ecommerce is enabled, 0 or 1
$siteSearch null | integer Whether site search is enabled, 0 or 1
$searchKeywordParameters string Comma separated list of search keyword parameter names
$searchCategoryParameters string Comma separated list of search category parameter names
$excludedIps string Comma separated list of IPs to exclude from being tracked (allows wildcards)
$excludedQueryParameters null | string
$timezone string Timezone
$currency string Currency code
$group string Group name where this website belongs
$startDate string Date at which the statistics for this website will start. Defaults to today's date in YYYY-MM-DD format
$excludedUserAgents null | string
$keepURLFragments integer | null If 1, URL fragments will be kept when tracking. If 2, they will be removed. If 0, the default global behavior will be used.
$type string The Website type, default value is "website"
$settingValues array | null JSON serialized settings eg {settingName: settingValue, ...}
$excludeUnknownUrls boolean | null Track only URL matching one of website URLs
return boolean true on success

updateSiteCreatedTime() public method

Updates the field ts_created for the specified websites.
public updateSiteCreatedTime ( $idSites, Date $minDate )
$idSites int Id Site to update ts_created
$minDate Piwik\Date Date to set as creation date. To play it safe it will subtract one more day.