PHP Class Piwik\Archive

You can use **Archive** instances to get data that was archived for one or more sites, for one or more periods and one optional segment. If archive data is not found, this class will initiate the archiving process. 1 **Archive** instances must be created using the {@link build()} factory method; they cannot be constructed. You can search for metrics (such as nb_visits) using the {@link getNumeric()} and {@link getDataTableFromNumeric()} methods. You can search for reports using the {@link getBlob()}, {@link getDataTable()} and {@link getDataTableExpanded()} methods. If you're creating an API that returns report data, you may want to use the {@link createDataTableFromArchive()} helper function. ### Learn more Learn more about _archiving_ here. ### Limitations - You cannot get data for multiple range periods in a single query. - You cannot get data for periods of different types in a single query. ### Examples **_Querying metrics for an API method_** one site and one period $archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08'); return $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions')); all sites and multiple dates $archive = Archive::build($idSite = 'all', $period = 'month', $date = '2013-01-02,2013-03-08'); return $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions')); **_Querying and using metrics immediately_** one site and one period $archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08'); $data = $archive->getNumeric(array('nb_visits', 'nb_actions')); $visits = $data['nb_visits']; $actions = $data['nb_actions']; ... do something w/ metric data ... multiple sites and multiple dates $archive = Archive::build($idSite = '1,2,3', $period = 'month', $date = '2013-01-02,2013-03-08'); $data = $archive->getNumeric('nb_visits'); $janSite1Visits = $data['1']['2013-01-01,2013-01-31']['nb_visits']; $febSite1Visits = $data['1']['2013-02-01,2013-02-28']['nb_visits']; ... etc. **_Querying for reports_** $archive = Archive::build($idSite = 1, $period = 'week', $date = '2013-03-08'); $dataTable = $archive->getDataTable('MyPlugin_MyReport'); ... manipulate $dataTable ... return $dataTable; **_Querying a report for an API method_** public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false) { $dataTable = Archive::createDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded); return $dataTable; } **_Querying data for multiple range periods_** get data for first range $archive = Archive::build($idSite = 1, $period = 'range', $date = '2013-03-08,2013-03-12'); $dataTable = $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions')); get data for second range $archive = Archive::build($idSite = 1, $period = 'range', $date = '2013-03-15,2013-03-20'); $dataTable = $archive->getDataTableFromNumeric(array('nb_visits', 'nb_actions')); [1]: The archiving process will not be launched if browser archiving is disabled and the current request came from a browser.
Mostrar archivo Open project: piwik/piwik Class Usage Examples

Public Methods

Method Description
build ( string | integer | array $idSites, string $period, Date | string $strDate, boolean | false | string $segment = false, boolean | false | string $_restrictSitesToLogin = false ) : static Returns a new Archive instance that will query archive data for the given set of sites and periods, using an optional Segment.
clearStaticCache ( )
createDataTableFromArchive ( string $recordName, integer | string | array $idSite, string $period, string $date, string $segment, boolean $expanded = false, boolean $flat = false, integer | null $idSubtable = null, integer | null $depth = null ) : DataTable | Piwik\DataTable\Map Helper function that creates an Archive instance and queries for report data using query parameter data. API methods can use this method to reduce code redundancy.
factory ( Segment $segment, array $periods, array $idSites, boolean $idSiteIsAll = false, boolean $isMultipleDate = false ) : Archive Returns a new Archive instance that will query archive data for the given set of sites and periods, using an optional segment.
getDataTable ( string $name, integer | string | null $idSubtable = null ) : DataTable | Piwik\DataTable\Map Queries and returns one or more reports as DataTable instances.
getDataTableExpanded ( string $name, integer | string | null $idSubtable = null, integer | null $depth = null, boolean $addMetadataSubtableId = true ) : DataTable | Piwik\DataTable\Map Queries and returns one report with all of its subtables loaded.
getDataTableFromNumeric ( string | array $names ) : DataTable | Piwik\DataTable\Map Queries and returns metric data in a DataTable instance.
getDataTableFromNumericAndMergeChildren ( $names ) : DataTable | Piwik\DataTable\Map Similar to {@link getDataTableFromNumeric()} but merges all children on the created DataTable.
getNumeric ( string | array $names ) : false | integer | array Queries and returns metric data in an array.
getParams ( ) : Piwik\Archive\Parameters Returns an object describing the set of sites, the set of periods and the segment this Archive will query data for.

Protected Methods

Method Description
__construct ( Piwik\Archive\Parameters $params, boolean $forceIndexedBySite = false, boolean $forceIndexedByDate = false )
get ( array | string $archiveNames, $archiveDataType, null | integer $idSubtable = null ) : Piwik\Archive\DataCollection Queries archive tables for data and returns the result.

Private Methods

Method Description
cacheArchiveIdsAfterLaunching ( array $archiveGroups, array $plugins ) Gets the IDs of the archives we're querying for and stores them in $this->archives.
cacheArchiveIdsWithoutLaunching ( array $plugins ) Gets the IDs of the archives we're querying for and stores them in $this->archives.
formatNumericValue ( $value )
getArchiveGroupOfPlugin ( $plugin ) Returns the archiving group identifier given a plugin.
getArchiveIds ( string $archiveNames ) : array Returns archive IDs for the sites, periods and archive names that are being queried. This function will use the idarchive cache if it has the right data, query archive tables for IDs w/o launching archiving, or launch archiving and get the idarchive from ArchiveProcessor instances.
getDoneStringForPlugin ( string $plugin, $idSites ) : string Returns the done string flag for a plugin using this instance's segment & periods.
getIdArchivesByMonth ( $doneFlags )
getPeriodLabel ( )
getPluginForReport ( string $report ) : string Returns the name of the plugin that archives a given report.
getRequestedPlugins ( array $archiveNames ) : array Returns the list of plugins that archive the given reports.
getResultIndices ( ) : array Returns an array describing what metadata to use when indexing a query result.
getSiteIdsThatAreRequestedInThisArchiveButWereNotInvalidatedYet ( )
initializeArchiveIdCache ( string $doneFlag ) Initializes the archive ID cache ($this->idarchives) for a particular 'done' flag.
invalidatedReportsIfNeeded ( )
prepareArchive ( array $archiveGroups, Site $site, piwik\Period $period )

Method Details

__construct() protected method

protected __construct ( Piwik\Archive\Parameters $params, boolean $forceIndexedBySite = false, boolean $forceIndexedByDate = false )
$params Piwik\Archive\Parameters
$forceIndexedBySite boolean Whether to force index the result of a query by site ID.
$forceIndexedByDate boolean Whether to force index the result of a query by period.

build() public static method

This method uses data that is found in query parameters, so the parameters to this function can be string values. If you want to create an Archive instance with an array of Period instances, use {@link Archive::factory()}.
public static build ( string | integer | array $idSites, string $period, Date | string $strDate, boolean | false | string $segment = false, boolean | false | string $_restrictSitesToLogin = false ) : static
$idSites string | integer | array A single ID (eg, `'1'`), multiple IDs (eg, `'1,2,3'` or `array(1, 2, 3)`), or `'all'`.
$period string 'day', `'week'`, `'month'`, `'year'` or `'range'`
$strDate Date | string 'YYYY-MM-DD', magic keywords (ie, 'today'; {@link Date::factory()} or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD').
$segment boolean | false | string Segment definition or false if no segment should be used. {@link Piwik\Segment}
$_restrictSitesToLogin boolean | false | string Used only when running as a scheduled task.
return static

clearStaticCache() public static method

public static clearStaticCache ( )

createDataTableFromArchive() public static method

Helper function that creates an Archive instance and queries for report data using query parameter data. API methods can use this method to reduce code redundancy.
public static createDataTableFromArchive ( string $recordName, integer | string | array $idSite, string $period, string $date, string $segment, boolean $expanded = false, boolean $flat = false, integer | null $idSubtable = null, integer | null $depth = null ) : DataTable | Piwik\DataTable\Map
$recordName string The name of the report to return.
$idSite integer | string | array @see {@link build()}
$period string @see {@link build()}
$date string @see {@link build()}
$segment string @see {@link build()}
$expanded boolean If true, loads all subtables. See {@link getDataTableExpanded()}
$flat boolean If true, loads all subtables and disabled all recursive filters.
$idSubtable integer | null See {@link getDataTableExpanded()}
$depth integer | null See {@link getDataTableExpanded()}
return DataTable | Piwik\DataTable\Map

factory() public static method

This method uses an array of Period instances and a Segment instance, instead of strings like {@link build()}. If you want to create an Archive instance using data found in query parameters, use {@link build()}.
public static factory ( Segment $segment, array $periods, array $idSites, boolean $idSiteIsAll = false, boolean $isMultipleDate = false ) : Archive
$segment Segment The segment to use. For no segment, use `new Segment('', $idSites)`.
$periods array An array of Period instances.
$idSites array An array of site IDs (eg, `array(1, 2, 3)`).
$idSiteIsAll boolean Whether `'all'` sites are being queried or not. If true, then the result of querying functions will be indexed by site, regardless of whether `count($idSites) == 1`.
$isMultipleDate boolean Whether multiple dates are being queried or not. If true, then the result of querying functions will be indexed by period, regardless of whether `count($periods) == 1`.
return Archive

get() protected method

Queries archive tables for data and returns the result.
protected get ( array | string $archiveNames, $archiveDataType, null | integer $idSubtable = null ) : Piwik\Archive\DataCollection
$archiveNames array | string
$archiveDataType
$idSubtable null | integer
return Piwik\Archive\DataCollection

getDataTable() public method

This method will query blob data that is a serialized array of of {@link DataTable\Row}'s and unserialize it. If multiple sites were requested in {@link build()} or {@link factory()} the result will be a {@link DataTable\Map} that is indexed by site ID. If multiple periods were requested in {@link build()} or {@link factory()} the result will be a DataTable\Map that is indexed by period. The site ID index is always first, so if multiple sites & periods were requested, the result will be a {@link DataTable\Map} indexed by site ID which contains {@link DataTable\Map} instances that are indexed by period.
public getDataTable ( string $name, integer | string | null $idSubtable = null ) : DataTable | Piwik\DataTable\Map
$name string The name of the record to get. This method can only query one record at a time.
$idSubtable integer | string | null The ID of the subtable to get (if any).
return DataTable | Piwik\DataTable\Map A DataTable if multiple sites and periods were not requested. An appropriately indexed {@link DataTable\Map} if otherwise.

getDataTableExpanded() public method

If multiple sites were requested in {@link build()} or {@link factory()} the result will be a DataTable\Map that is indexed by site ID. If multiple periods were requested in {@link build()} or {@link factory()} the result will be a DataTable\Map that is indexed by period. The site ID index is always first, so if multiple sites & periods were requested, the result will be a {@link DataTable\Map indexed} by site ID which contains {@link DataTable\Map} instances that are indexed by period.
public getDataTableExpanded ( string $name, integer | string | null $idSubtable = null, integer | null $depth = null, boolean $addMetadataSubtableId = true ) : DataTable | Piwik\DataTable\Map
$name string The name of the record to get.
$idSubtable integer | string | null The ID of the subtable to get (if any). The subtable will be expanded.
$depth integer | null The maximum number of subtable levels to load. If null, all levels are loaded. For example, if `1` is supplied, then the DataTable returned will have its subtables loaded. Those subtables, however, will NOT have their subtables loaded.
$addMetadataSubtableId boolean Whether to add the database subtable ID as metadata to each datatable, or not.
return DataTable | Piwik\DataTable\Map

getDataTableFromNumeric() public method

If multiple sites were requested in {@link build()} or {@link factory()} the result will be a DataTable\Map that is indexed by site ID. If multiple periods were requested in {@link build()} or {@link factory()} the result will be a {@link DataTable\Map} that is indexed by period. The site ID index is always first, so if multiple sites & periods were requested, the result will be a {@link DataTable\Map} indexed by site ID which contains {@link DataTable\Map} instances that are indexed by period. _Note: Every DataTable instance returned will have at most one row in it. The contents of each row will be the requested metrics for the appropriate site and period._
public getDataTableFromNumeric ( string | array $names ) : DataTable | Piwik\DataTable\Map
$names string | array One or more archive names, eg, 'nb_visits', 'Referrers_distinctKeywords', etc.
return DataTable | Piwik\DataTable\Map A DataTable if multiple sites and periods were not requested. An appropriately indexed DataTable\Map if otherwise.

getDataTableFromNumericAndMergeChildren() public method

This is the same as doing $this->getDataTableFromNumeric()->mergeChildren() but this way it is much faster.
public getDataTableFromNumericAndMergeChildren ( $names ) : DataTable | Piwik\DataTable\Map
return DataTable | Piwik\DataTable\Map

getNumeric() public method

If multiple sites were requested in {@link build()} or {@link factory()} the result will be indexed by site ID. If multiple periods were requested in {@link build()} or {@link factory()} the result will be indexed by period. The site ID index is always first, so if multiple sites & periods were requested, the result will be indexed by site ID first, then period.
public getNumeric ( string | array $names ) : false | integer | array
$names string | array One or more archive names, eg, `'nb_visits'`, `'Referrers_distinctKeywords'`, etc.
return false | integer | array `false` if there is no data to return, a single numeric value if we're not querying for multiple sites/periods, or an array if multiple sites, periods or names are queried for.

getParams() public method

Returns an object describing the set of sites, the set of periods and the segment this Archive will query data for.
public getParams ( ) : Piwik\Archive\Parameters
return Piwik\Archive\Parameters