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.
Exibir arquivo
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 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
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 |
|
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.
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 |
|