PHP Class Piwik\DataTable

### The Basics DataTables consist of rows and each row consists of columns. A column value can be a numeric, a string or an array. Every row has an ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}. DataTables are hierarchical data structures. Each row can also contain an additional nested sub-DataTable (commonly referred to as a 'subtable'). Both DataTables and DataTable rows can hold **metadata**. _DataTable metadata_ is information regarding all the data, such as the site or period that the data is for. _Row metadata_ is information regarding that row, such as a browser logo or website URL. Finally, all DataTables contain a special _summary_ row. This row, if it exists, is always at the end of the DataTable. ### Populating DataTables Data can be added to DataTables in three different ways. You can either: 1. create rows one by one and add them through {@link addRow()} then truncate if desired, 2. create an array of DataTable\Row instances or an array of arrays and add them using {@link addRowsFromArray()} or {@link addRowsFromSimpleArray()} then truncate if desired, 3. or set the maximum number of allowed rows (with {@link setMaximumAllowedRows()}) and add rows one by one. If you want to eventually truncate your data (standard practice for all Piwik plugins), the third method is the most memory efficient. It is, unfortunately, not always possible to use since it requires that the data be sorted before adding. ### Manipulating DataTables There are two ways to manipulate a DataTable. You can either: 1. manually iterate through each row and manipulate the data, 2. or you can use predefined filters. A filter is a class that has a 'filter' method which will manipulate a DataTable in some way. There are several predefined Filters that allow you to do common things, such as, - add a new column to each row, - add new metadata to each row, - modify an existing column value for each row, - sort an entire DataTable, - and more. Using these filters instead of writing your own code will increase code clarity and reduce code redundancy. Additionally, filters have the advantage that they can be applied to DataTable\Map instances. So you can visit every DataTable in a {@link DataTable\Map} without having to write a recursive visiting function. All predefined filters exist in the **Piwik\DataTable\BaseFilter** namespace. _Note: For convenience, anonymous functions can be used as DataTable filters._ ### Applying Filters Filters can be applied now (via {@link filter()}), or they can be applied later (via {@link queueFilter()}). Filters that sort rows or manipulate the number of rows should be applied right away. Non-essential, presentation filters should be queued. ### Learn more - See **{@link ArchiveProcessor}** to learn how DataTables are persisted. ### Examples **Populating a DataTable** adding one row at a time $dataTable = new DataTable(); $dataTable->addRow(new Row(array( Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), Row::METADATA => array('url' => 'http://thing1.com') ))); $dataTable->addRow(new Row(array( Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2), Row::METADATA => array('url' => 'http://thing2.com') ))); using an array of rows $dataTable = new DataTable(); $dataTable->addRowsFromArray(array( array( Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), Row::METADATA => array('url' => 'http://thing1.com') ), array( Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2), Row::METADATA => array('url' => 'http://thing2.com') ) )); using a "simple" array $dataTable->addRowsFromSimpleArray(array( array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1), array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2) )); **Getting & setting metadata** $dataTable = \Piwik\Plugins\Referrers\API::getInstance()->getSearchEngines($idSite = 1, $period = 'day', $date = '2007-07-24'); $oldPeriod = $dataTable->metadata['period']; $dataTable->metadata['period'] = Period\Factory::build('week', Date::factory('2013-10-18')); **Serializing & unserializing** $maxRowsInTable = Config::getInstance()->General['datatable_archiving_maximum_rows_standard'];j $dataTable = // ... build by aggregating visits ... $serializedData = $dataTable->getSerialized($maxRowsInTable, $maxRowsInSubtable = $maxRowsInTable, $columnToSortBy = Metrics::INDEX_NB_VISITS); $serializedDataTable = $serializedData[0]; $serailizedSubTable = $serializedData[$idSubtable]; **Filtering for an API method** public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false) { $dataTable = Archive::getDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded); $dataTable->filter('Sort', array(Metrics::INDEX_NB_VISITS, 'desc', $naturalSort = false, $expanded)); $dataTable->queueFilter('ReplaceColumnNames'); $dataTable->queueFilter('ColumnCallbackAddMetadata', array('label', 'url', __NAMESPACE__ . '\getUrlFromLabelForMyReport')); return $dataTable; }
Inheritance: implements Piwik\DataTable\DataTableInterface, implements IteratorAggregate, implements ArrayAccess
Show file Open project: piwik/piwik Class Usage Examples

Protected Properties

Property Type Description
$currentId integer Id assigned to the DataTable, used to lookup the table using the DataTable_Manager
$depthLevel integer Current depth level of this data table 0 is the parent data table
$disabledFilters array List of disabled filter names eg 'Limit' or 'Sort'
$enableRecursiveFilters boolean When the table and all subtables are loaded, this flag will be set to true to ensure filters are applied to all subtables
$enableRecursiveSort boolean Defaults to false for performance reasons (most of the time we don't need recursive sorting so we save a looping over the dataTable)
$indexNotUpToDate boolean This flag is set to false once we modify the table in a way that outdates the index
$maximumAllowedRows integer If adding more rows is attempted, the extra rows get summed to the summary row.
$queuedFilters array List of BaseFilter queued to this table
$rebuildIndexContinuously boolean This is to optimize and not rebuild the full Index in the case where we add row, getRowFromLabel, addRow, getRowFromLabel thousands of times.
$rows Piwik\DataTable\Row[] Array of Row
$rowsCountBeforeLimitFilter integer We keep track of the number of rows before applying the LIMIT filter that deletes some rows
$rowsIndexByLabel array
$summaryRow Piwik\DataTable\Row
$tableSortedBy string Column name of last time the table was sorted

Public Methods

Method Description
__clone ( ) Clone. Called when cloning the datatable. We need to make sure to create a new datatableId.
__construct ( ) Constructor. Creates an empty DataTable.
__destruct ( ) Destructor. Makes sure DataTable memory will be cleaned up.
__sleep ( )
__toString ( ) : string Returns a string representation of this DataTable for convenient viewing.
addDataTable ( DataTable $tableToSum ) Sums a DataTable to this one.
addRow ( Row $row ) : Row Adds a row to this table.
addRowFromArray ( array $row ) Adds a new row from an array.
addRowFromSimpleArray ( array $row ) Adds a new row a from an array of column values.
addRowsFromArray ( array $array ) Adds multiple rows from an array.
addRowsFromSerializedArray ( string $serialized ) Adds a set of rows from a serialized DataTable string.
addRowsFromSimpleArray ( array $array ) Adds multiple rows from an array containing arrays of column values.
addSummaryRow ( Row $row ) : Row Sets the summary row.
applyQueuedFilters ( ) Applies all filters that were previously queued to the table. See {@link queueFilter()} for more information.
clearQueuedFilters ( ) Unsets all queued filters.
deleteColumn ( string $name ) Delete a column by name in every row. This change is NOT applied recursively to all subtables.
deleteColumns ( array $names, boolean $deleteRecursiveInSubtables = false ) Deletes several columns by name in every row.
deleteRow ( integer $id ) Deletes a row by ID.
deleteRows ( array $rowIds ) Deletes a set of rows by ID.
deleteRowsOffset ( integer $offset, integer | null $limit = null ) : integer Deletes rows from $offset to $offset + $limit.
disableFilter ( string $className ) Disable a specific filter to run on this DataTable in case you have already applied this filter or if you will handle this filter manually by using a custom filter. Be aware if you disable a given filter, that filter won't be ever executed. Even if another filter calls this filter on the DataTable.
disableRecursiveFilters ( )
enableRecursiveFilters ( ) Enables recursive filtering. If this method is called then the {@link filter()} method will apply filters to every subtable in addition to this instance.
enableRecursiveSort ( ) Enables recursive sorting. If this method is called {@link sort()} will also sort all subtables.
filter ( string | Closur\Closure $className, array $parameters = [] ) Applies a filter to this datatable.
filterSubtables ( string | Closur\Closure $className, array $parameters = [] ) Applies a filter to all subtables but not to this datatable.
fromSerializedArray ( string $data ) : DataTable Creates a new DataTable instance from a serialized DataTable string.
getAllTableMetadata ( ) : array Returns all table metadata.
getColumn ( string $name ) : array Returns an array containing all column values for the requested column.
getColumns ( ) : array Returns the names of every column this DataTable contains. This method will return the columns of the first row with data and will assume they occur in every other row as well.
getColumnsStartingWith ( string $namePrefix ) : array Returns an array containing all column values of columns whose name starts with $name.
getEmptyClone ( boolean $keepFilters = true ) : DataTable Returns an empty DataTable with the same metadata and queued filters as $this one.
getFirstRow ( ) : Row | false Returns the first row of the DataTable.
getId ( ) : integer Returns the DataTable ID.
getIterator ( ) : ArrayIterator | Row[]
getLastRow ( ) : Row | false Returns the last row of the DataTable. If there is a summary row, it will always be considered the last row.
getMetadata ( string $name ) : mixed | false Returns metadata by name.
getRowFromId ( integer $id ) : Row | false Returns a row by ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}.
getRowFromIdSubDataTable ( integer $idSubTable ) : Row | false Returns the row that has a subtable with ID matching $idSubtable.
getRowFromLabel ( string $label ) : Row | false Returns the Row whose 'label' column is equal to $label.
getRowIdFromLabel ( string $label ) : integer Returns the row id for the row whose 'label' column is equal to $label.
getRows ( ) : Row[] Returns the array of Rows.
getRowsCount ( ) : integer Returns the number of rows in the table including the summary row.
getRowsCountRecursive ( ) : integer Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable summed with the row count of each descendant subtable.
getRowsCountWithoutSummaryRow ( )
getRowsMetadata ( string $name ) : array Returns an array containing the requested metadata value of each row.
getRowsWithoutSummaryRow ( )
getSerialized ( integer $maximumRowsInDataTable = null, integer $maximumRowsInSubDataTable = null, string $columnToSortByBeforeTruncation = null ) : array Serializes an entire DataTable hierarchy and returns the array of serialized DataTables.
getSortedByColumnName ( ) : false | string Returns the name of the column this table was sorted by (if any).
isEqual ( DataTable $table1, DataTable $table2 ) : boolean Returns true if both DataTable instances are exactly the same.
isSortRecursiveEnabled ( )
makeFromIndexedArray ( array $array, array | null $subtablePerLabel = null ) : DataTable Rewrites the input $array
makeFromSimpleArray ( array $array ) : DataTable Returns a new DataTable created with data from a 'simple' array.
mergeSubtables ( string | boolean $labelColumn = false, boolean $useMetadataColumn = false ) : DataTable Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables.
offsetExists ( $offset )
offsetGet ( $offset )
offsetSet ( $offset, $value )
offsetUnset ( $offset )
queueFilter ( string | Closur\Closure $className, array $parameters = [] ) Adds a filter and a list of parameters to the list of queued filters. These filters will be executed when {@link applyQueuedFilters()} is called.
queueFilterSubtables ( string | Closur\Closure $className, array $parameters = [] ) Adds a filter and a list of parameters to the list of queued filters of all subtables. These filters will be executed when {@link applyQueuedFilters()} is called.
rebuildIndex ( ) Rebuilds the index used to lookup a row by label
renameColumn ( string $oldName, string $newName ) Rename a column in every row. This change is applied recursively to all subtables.
setAllTableMetadata ( $metadata ) Sets metadata, erasing existing values.
setLabelsHaveChanged ( )
setMaximumAllowedRows ( integer $maximumAllowedRows ) Sets the maximum number of rows allowed in this datatable (including the summary row). If adding more then the allowed number of rows is attempted, the extra rows are summed to the summary row.
setMaximumDepthLevelAllowedAtLeast ( integer $atLeastLevel ) Sets the maximum depth level to at least a certain value. If the current value is greater than $atLeastLevel, the maximum nesting level is not changed.
setMetadata ( string $name, mixed $value ) Sets a metadata value by name.
setMetadataValues ( array $values ) Sets several metadata values by name.
setRows ( $rows )
setTableSortedBy ( $column )
sort ( string $functionCallback, string $columnSortedBy ) Sorts the DataTable rows using the supplied callback function.
walkPath ( array $path, array | boolean $missingRowColumns = false, integer $maxSubtableRows ) : array Traverses a DataTable tree using an array of labels and returns the row it finds or false if it cannot find one. The number of path segments that were successfully walked is also returned.

Protected Methods

Method Description
aggregateRowFromSimpleTable ( $row )
aggregateRowWithLabel ( Row $row, $columnAggregationOps ) Aggregates the $row columns to this table.

Private Methods

Method Description
unserializeRows ( string $serialized ) : array It is faster to unserialize existing serialized Row instances to "Piwik_DataTable_SerializedRow" and access the $row->c property than implementing a "__wakeup" method in the Row instance to map the "$row->c" to $row->columns etc. We're talking here about 15% faster reports aggregation in some cases. To be concrete: We have a test where Archiving a year takes 1700 seconds with "__wakeup" and 1400 seconds with this method. Yes, it takes 300 seconds to wake up millions of rows. We should be able to remove this code here end 2015 and use the "__wakeup" way by then.

Method Details

__clone() public method

If we do not increase tableId it can result in segmentation faults when destructing a datatable.
public __clone ( )

__construct() public method

Constructor. Creates an empty DataTable.
public __construct ( )

__destruct() public method

Destructor. Makes sure DataTable memory will be cleaned up.
public __destruct ( )

__sleep() public method

public __sleep ( )

__toString() public method

_Note: This uses the **html** DataTable renderer._
public __toString ( ) : string
return string

addDataTable() public method

This method will sum rows that have the same label. If a row is found in $tableToSum whose label is not found in $this, the row will be added to $this. If the subtables for this table are loaded, they will be summed as well. Rows are summed together by summing individual columns. By default columns are summed by adding one column value to another. Some columns cannot be aggregated this way. In these cases, the {@link COLUMN_AGGREGATION_OPS_METADATA_NAME} metadata can be used to specify a different type of operation.
public addDataTable ( DataTable $tableToSum )
$tableToSum DataTable

addRow() public method

If {@link setMaximumAllowedRows()} was called and the current row count is at the maximum, the new row will be summed to the summary row. If there is no summary row, this row is set as the summary row.
public addRow ( Row $row ) : Row
$row Piwik\DataTable\Row
return Piwik\DataTable\Row `$row` or the summary row if we're at the maximum number of rows.

addRowFromArray() public method

You can add row metadata with this method.
public addRowFromArray ( array $row )
$row array eg. `array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'), Row::METADATA => array('mymetadata' => 'myvalue'))`

addRowFromSimpleArray() public method

Row metadata cannot be added with this method.
public addRowFromSimpleArray ( array $row )
$row array eg. `array('name' => 'google analytics', 'license' => 'commercial')`

addRowsFromArray() public method

You can add row metadata with this method.
public addRowsFromArray ( array $array )
$array array Array with the following structure array( // row1 array( Row::COLUMNS => array( col1_name => value1, col2_name => value2, ...), Row::METADATA => array( metadata1_name => value1, ...), // see Row ), // row2 array( ... ), )

addRowsFromSerializedArray() public method

See {@link serialize()}. _Note: This function will successfully load DataTables serialized by Piwik 1.X._
public addRowsFromSerializedArray ( string $serialized )
$serialized string A string with the format of a string in the array returned by {@link serialize()}.

addRowsFromSimpleArray() public method

Row metadata cannot be added with this method.
public addRowsFromSimpleArray ( array $array )
$array array Array with the following structure: array( array( col1_name => valueA, col2_name => valueC, ...), array( col1_name => valueB, col2_name => valueD, ...), )

addSummaryRow() public method

_Note: A DataTable can have only one summary row._
public addSummaryRow ( Row $row ) : Row
$row Piwik\DataTable\Row
return Piwik\DataTable\Row Returns `$row`.

aggregateRowFromSimpleTable() protected method

protected aggregateRowFromSimpleTable ( $row )
$row

aggregateRowWithLabel() protected method

$row must have a column "label". The $row will be summed to this table's row with the same label.
protected aggregateRowWithLabel ( Row $row, $columnAggregationOps )
$row Piwik\DataTable\Row

applyQueuedFilters() public method

Applies all filters that were previously queued to the table. See {@link queueFilter()} for more information.
public applyQueuedFilters ( )

clearQueuedFilters() public method

Unsets all queued filters.
public clearQueuedFilters ( )

deleteColumn() public method

Delete a column by name in every row. This change is NOT applied recursively to all subtables.
public deleteColumn ( string $name )
$name string Column name to delete.

deleteColumns() public method

Deletes several columns by name in every row.
public deleteColumns ( array $names, boolean $deleteRecursiveInSubtables = false )
$names array List of column names to delete.
$deleteRecursiveInSubtables boolean Whether to apply this change to all subtables or not.

deleteRow() public method

Deletes a row by ID.
public deleteRow ( integer $id )
$id integer The row ID.

deleteRows() public method

Deletes a set of rows by ID.
public deleteRows ( array $rowIds )
$rowIds array The list of row IDs to delete.

deleteRowsOffset() public method

Deletes rows from $offset to $offset + $limit.
public deleteRowsOffset ( integer $offset, integer | null $limit = null ) : integer
$offset integer The offset to start deleting rows from.
$limit integer | null The number of rows to delete. If `null` all rows after the offset will be removed.
return integer The number of rows deleted.

disableFilter() public method

Disable a specific filter to run on this DataTable in case you have already applied this filter or if you will handle this filter manually by using a custom filter. Be aware if you disable a given filter, that filter won't be ever executed. Even if another filter calls this filter on the DataTable.
public disableFilter ( string $className )
$className string eg 'Limit' or 'Sort'. Passing a `Closure` or an `array($class, $methodName)` is not supported yet. We check for exact match. So if you disable 'Limit' and call `->filter('Limit')` this filter won't be executed. If you call `->filter('Piwik\DataTable\Filter\Limit')` that filter will be executed. See it as a feature.

disableRecursiveFilters() public method

enableRecursiveFilters() public method

Enables recursive filtering. If this method is called then the {@link filter()} method will apply filters to every subtable in addition to this instance.

enableRecursiveSort() public method

Enables recursive sorting. If this method is called {@link sort()} will also sort all subtables.
public enableRecursiveSort ( )

filter() public method

If {@link enableRecursiveFilters()} was called, the filter will be applied to all subtables as well.
public filter ( string | Closur\Closure $className, array $parameters = [] )
$className string | Closur\Closure Class name, eg. `"Sort"` or "Piwik\DataTable\Filters\Sort"`. If no namespace is supplied, `Piwik\DataTable\BaseFilter` is assumed. This parameter can also be a closure that takes a DataTable as its first parameter.
$parameters array Array of extra parameters to pass to the filter.

filterSubtables() public method

Applies a filter to all subtables but not to this datatable.
public filterSubtables ( string | Closur\Closure $className, array $parameters = [] )
$className string | Closur\Closure Class name, eg. `"Sort"` or "Piwik\DataTable\Filters\Sort"`. If no namespace is supplied, `Piwik\DataTable\BaseFilter` is assumed. This parameter can also be a closure that takes a DataTable as its first parameter.
$parameters array Array of extra parameters to pass to the filter.

fromSerializedArray() public static method

See {@link getSerialized()} and {@link addRowsFromSerializedArray()} for more information on DataTable serialization.
public static fromSerializedArray ( string $data ) : DataTable
$data string
return DataTable

getAllTableMetadata() public method

Returns all table metadata.
public getAllTableMetadata ( ) : array
return array

getColumn() public method

Returns an array containing all column values for the requested column.
public getColumn ( string $name ) : array
$name string The column name.
return array The array of column values.

getColumns() public method

_ Note: If column names still use their in-database INDEX values (@see Metrics), they will be converted to their string name in the array result._
public getColumns ( ) : array
return array Array of string column names.

getColumnsStartingWith() public method

Returns an array containing all column values of columns whose name starts with $name.
public getColumnsStartingWith ( string $namePrefix ) : array
$namePrefix string The column name prefix.
return array The array of column values.

getEmptyClone() public method

Returns an empty DataTable with the same metadata and queued filters as $this one.
public getEmptyClone ( boolean $keepFilters = true ) : DataTable
$keepFilters boolean Whether to pass the queued filter list to the new DataTable or not.
return DataTable

getFirstRow() public method

Returns the first row of the DataTable.
public getFirstRow ( ) : Row | false
return Piwik\DataTable\Row | false The first row or `false` if it cannot be found.

getId() public method

Returns the DataTable ID.
public getId ( ) : integer
return integer

getIterator() public method

public getIterator ( ) : ArrayIterator | Row[]
return ArrayIterator | Piwik\DataTable\Row[]

getLastRow() public method

Returns the last row of the DataTable. If there is a summary row, it will always be considered the last row.
public getLastRow ( ) : Row | false
return Piwik\DataTable\Row | false The last row or `false` if it cannot be found.

getMetadata() public method

Returns metadata by name.
public getMetadata ( string $name ) : mixed | false
$name string The metadata name.
return mixed | false The metadata value or `false` if it cannot be found.

getRowFromId() public method

Returns a row by ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}.
public getRowFromId ( integer $id ) : Row | false
$id integer The row ID.
return Piwik\DataTable\Row | false The Row or false if not found.

getRowFromIdSubDataTable() public method

Returns the row that has a subtable with ID matching $idSubtable.
public getRowFromIdSubDataTable ( integer $idSubTable ) : Row | false
$idSubTable integer The subtable ID.
return Piwik\DataTable\Row | false The row or false if not found

getRowFromLabel() public method

This method executes in constant time except for the first call which caches row label => row ID mappings.
public getRowFromLabel ( string $label ) : Row | false
$label string `'label'` column value to look for.
return Piwik\DataTable\Row | false The row if found, `false` if otherwise.

getRowIdFromLabel() public method

This method executes in constant time except for the first call which caches row label => row ID mappings.
public getRowIdFromLabel ( string $label ) : integer
$label string `'label'` column value to look for.
return integer The row ID.

getRows() public method

Returns the array of Rows.
public getRows ( ) : Row[]
return Piwik\DataTable\Row[]

getRowsCount() public method

Returns the number of rows in the table including the summary row.
public getRowsCount ( ) : integer
return integer

getRowsCountRecursive() public method

Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable summed with the row count of each descendant subtable.
public getRowsCountRecursive ( ) : integer
return integer

getRowsCountWithoutSummaryRow() public method

getRowsMetadata() public method

Returns an array containing the requested metadata value of each row.
public getRowsMetadata ( string $name ) : array
$name string The metadata column to return.
return array

getRowsWithoutSummaryRow() public method

getSerialized() public method

The first element in the returned array will be the serialized representation of this DataTable. Every subsequent element will be a serialized subtable. This DataTable and subtables can optionally be truncated before being serialized. In most cases where DataTables can become quite large, they should be truncated before being persisted in an archive. The result of this method is intended for use with the {@link ArchiveProcessor::insertBlobRecord()} method.
public getSerialized ( integer $maximumRowsInDataTable = null, integer $maximumRowsInSubDataTable = null, string $columnToSortByBeforeTruncation = null ) : array
$maximumRowsInDataTable integer If not null, defines the maximum number of rows allowed in the serialized DataTable.
$maximumRowsInSubDataTable integer If not null, defines the maximum number of rows allowed in serialized subtables.
$columnToSortByBeforeTruncation string The column to sort by before truncating, eg, `Metrics::INDEX_NB_VISITS`.
return array The array of serialized DataTables: array( // this DataTable (the root) 0 => 'eghuighahgaueytae78yaet7yaetae', // a subtable 1 => 'gaegae gh gwrh guiwh uigwhuige', // another subtable 2 => 'gqegJHUIGHEQjkgneqjgnqeugUGEQHGUHQE', // etc. );

getSortedByColumnName() public method

See {@link sort()}.
public getSortedByColumnName ( ) : false | string
return false | string The sorted column name or false if none.

isEqual() public static method

DataTables are equal if they have the same number of rows, if each row has a label that exists in the other table, and if each row is equal to the row in the other table with the same label. The order of rows is not important.
public static isEqual ( DataTable $table1, DataTable $table2 ) : boolean
$table1 DataTable
$table2 DataTable
return boolean

isSortRecursiveEnabled() public method

makeFromIndexedArray() public static method

array ( LABEL => array(col1 => X, col2 => Y), LABEL2 => array(col1 => X, col2 => Y), ) to a DataTable with rows that look like: array ( array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)), array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)), ) Will also convert arrays like: array ( LABEL => X, LABEL2 => Y, ) to: array ( array( Row::COLUMNS => array('label' => LABEL, 'value' => X)), array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)), )
public static makeFromIndexedArray ( array $array, array | null $subtablePerLabel = null ) : DataTable
$array array Indexed array, two formats supported, see above.
$subtablePerLabel array | null An array mapping label values with DataTable instances to associate as a subtable.
return DataTable

makeFromSimpleArray() public static method

See {@link addRowsFromSimpleArray()}.
public static makeFromSimpleArray ( array $array ) : DataTable
$array array
return DataTable

mergeSubtables() public method

Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables.
public mergeSubtables ( string | boolean $labelColumn = false, boolean $useMetadataColumn = false ) : DataTable
$labelColumn string | boolean If supplied the label of the parent row will be added to a new column in each subtable row. If set to, `'label'` each subtable row's label will be prepended w/ the parent row's label. So `'child_label'` becomes `'parent_label - child_label'`.
$useMetadataColumn boolean If true and if `$labelColumn` is supplied, the parent row's label will be added as metadata and not a new column.
return DataTable

offsetExists() public method

public offsetExists ( $offset )

offsetGet() public method

public offsetGet ( $offset )

offsetSet() public method

public offsetSet ( $offset, $value )

offsetUnset() public method

public offsetUnset ( $offset )

queueFilter() public method

Filters that prettify the column values or don't need the full set of rows should be queued. This way they will be run after the table is truncated which will result in better performance.
public queueFilter ( string | Closur\Closure $className, array $parameters = [] )
$className string | Closur\Closure The class name of the filter, eg. `'Limit'`.
$parameters array The parameters to give to the filter, eg. `array($offset, $limit)` for the Limit filter.

queueFilterSubtables() public method

Filters that prettify the column values or don't need the full set of rows should be queued. This way they will be run after the table is truncated which will result in better performance.
public queueFilterSubtables ( string | Closur\Closure $className, array $parameters = [] )
$className string | Closur\Closure The class name of the filter, eg. `'Limit'`.
$parameters array The parameters to give to the filter, eg. `array($offset, $limit)` for the Limit filter.

rebuildIndex() public method

Rebuilds the index used to lookup a row by label
public rebuildIndex ( )

renameColumn() public method

Rename a column in every row. This change is applied recursively to all subtables.
public renameColumn ( string $oldName, string $newName )
$oldName string Old column name.
$newName string New column name.

setAllTableMetadata() public method

Sets metadata, erasing existing values.
public setAllTableMetadata ( $metadata )

setLabelsHaveChanged() public method

setMaximumAllowedRows() public method

Sets the maximum number of rows allowed in this datatable (including the summary row). If adding more then the allowed number of rows is attempted, the extra rows are summed to the summary row.
public setMaximumAllowedRows ( integer $maximumAllowedRows )
$maximumAllowedRows integer If `0`, the maximum number of rows is unset.

setMaximumDepthLevelAllowedAtLeast() public static method

The maximum depth level determines the maximum number of subtable levels in the DataTable tree. For example, if it is set to 2, this DataTable is allowed to have subtables, but the subtables are not.
public static setMaximumDepthLevelAllowedAtLeast ( integer $atLeastLevel )
$atLeastLevel integer

setMetadata() public method

Sets a metadata value by name.
public setMetadata ( string $name, mixed $value )
$name string The metadata name.
$value mixed

setMetadataValues() public method

Sets several metadata values by name.
public setMetadataValues ( array $values )
$values array Array mapping metadata names with metadata values.

setRows() public method

public setRows ( $rows )

setTableSortedBy() public method

public setTableSortedBy ( $column )

sort() public method

Sorts the DataTable rows using the supplied callback function.
public sort ( string $functionCallback, string $columnSortedBy )
$functionCallback string A comparison callback compatible with {@link usort}.
$columnSortedBy string The column name `$functionCallback` sorts by. This is stored so we can determine how the DataTable was sorted in the future.

walkPath() public method

If $missingRowColumns is supplied, the specified path is created. When a subtable is encountered w/o the required label, a new row is created with the label, and a new subtable is added to the row. Read http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods#Traversal_methods) for more information about tree walking.
public walkPath ( array $path, array | boolean $missingRowColumns = false, integer $maxSubtableRows ) : array
$path array The path to walk. An array of label values. The first element refers to a row in this DataTable, the second in a subtable of the first row, the third a subtable of the second row, etc.
$missingRowColumns array | boolean The default columns to use when creating new rows. If this parameter is supplied, new rows will be created for path labels that cannot be found.
$maxSubtableRows integer The maximum number of allowed rows in new subtables. New subtables are only created if `$missingRowColumns` is provided.
return array First element is the found row or `false`. Second element is the number of path segments walked. If a row is found, this will be == to `count($path)`. Otherwise, it will be the index of the path segment that we could not find.

Property Details

$currentId protected property

Id assigned to the DataTable, used to lookup the table using the DataTable_Manager
protected int $currentId
return integer

$depthLevel protected property

Current depth level of this data table 0 is the parent data table
protected int $depthLevel
return integer

$disabledFilters protected property

List of disabled filter names eg 'Limit' or 'Sort'
protected array $disabledFilters
return array

$enableRecursiveFilters protected property

When the table and all subtables are loaded, this flag will be set to true to ensure filters are applied to all subtables
protected bool $enableRecursiveFilters
return boolean

$enableRecursiveSort protected property

Defaults to false for performance reasons (most of the time we don't need recursive sorting so we save a looping over the dataTable)
protected bool $enableRecursiveSort
return boolean

$indexNotUpToDate protected property

This flag is set to false once we modify the table in a way that outdates the index
protected bool $indexNotUpToDate
return boolean

$maximumAllowedRows protected property

If adding more rows is attempted, the extra rows get summed to the summary row.
protected int $maximumAllowedRows
return integer

$queuedFilters protected property

List of BaseFilter queued to this table
protected array $queuedFilters
return array

$rebuildIndexContinuously protected property

This is to optimize and not rebuild the full Index in the case where we add row, getRowFromLabel, addRow, getRowFromLabel thousands of times.
protected bool $rebuildIndexContinuously
return boolean

$rows protected property

Array of Row
protected Row[],Piwik\DataTable $rows
return Piwik\DataTable\Row[]

$rowsCountBeforeLimitFilter protected property

We keep track of the number of rows before applying the LIMIT filter that deletes some rows
protected int $rowsCountBeforeLimitFilter
return integer

$rowsIndexByLabel protected property

protected array $rowsIndexByLabel
return array

$summaryRow protected property

protected Row,Piwik\DataTable $summaryRow
return Piwik\DataTable\Row

$tableSortedBy protected property

Column name of last time the table was sorted
protected string $tableSortedBy
return string