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
Afficher le fichier Open project: piwik/piwik Class Usage Examples

Protected Properties

Свойство 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

Méthodes publiques

Méthode 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.

Méthodes protégées

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

Private Methods

Méthode 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 méthode

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

__construct() public méthode

Constructor. Creates an empty DataTable.
public __construct ( )

__destruct() public méthode

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

__sleep() public méthode

public __sleep ( )

__toString() public méthode

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

addDataTable() public méthode

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 méthode

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
Résultat Piwik\DataTable\Row `$row` or the summary row if we're at the maximum number of rows.

addRowFromArray() public méthode

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 méthode

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

addRowsFromArray() public méthode

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 méthode

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 méthode

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 méthode

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

aggregateRowFromSimpleTable() protected méthode

protected aggregateRowFromSimpleTable ( $row )
$row

aggregateRowWithLabel() protected méthode

$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 méthode

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

clearQueuedFilters() public méthode

Unsets all queued filters.
public clearQueuedFilters ( )

deleteColumn() public méthode

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 méthode

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 méthode

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

deleteRows() public méthode

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

deleteRowsOffset() public méthode

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.
Résultat integer The number of rows deleted.

disableFilter() public méthode

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 méthode

enableRecursiveFilters() public méthode

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 méthode

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

filter() public méthode

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 méthode

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 méthode

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

getAllTableMetadata() public méthode

Returns all table metadata.
public getAllTableMetadata ( ) : array
Résultat array

getColumn() public méthode

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

getColumns() public méthode

_ 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
Résultat array Array of string column names.

getColumnsStartingWith() public méthode

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.
Résultat array The array of column values.

getEmptyClone() public méthode

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.
Résultat DataTable

getFirstRow() public méthode

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

getId() public méthode

Returns the DataTable ID.
public getId ( ) : integer
Résultat integer

getIterator() public méthode

public getIterator ( ) : ArrayIterator | Row[]
Résultat ArrayIterator | Piwik\DataTable\Row[]

getLastRow() public méthode

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
Résultat Piwik\DataTable\Row | false The last row or `false` if it cannot be found.

getMetadata() public méthode

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

getRowFromId() public méthode

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.
Résultat Piwik\DataTable\Row | false The Row or false if not found.

getRowFromIdSubDataTable() public méthode

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

getRowFromLabel() public méthode

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.
Résultat Piwik\DataTable\Row | false The row if found, `false` if otherwise.

getRowIdFromLabel() public méthode

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.
Résultat integer The row ID.

getRows() public méthode

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

getRowsCount() public méthode

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

getRowsCountRecursive() public méthode

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
Résultat integer

getRowsCountWithoutSummaryRow() public méthode

getRowsMetadata() public méthode

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

getRowsWithoutSummaryRow() public méthode

getSerialized() public méthode

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`.
Résultat 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 méthode

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

isEqual() public static méthode

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
Résultat boolean

isSortRecursiveEnabled() public méthode

makeFromIndexedArray() public static méthode

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.
Résultat DataTable

makeFromSimpleArray() public static méthode

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

mergeSubtables() public méthode

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.
Résultat DataTable

offsetExists() public méthode

public offsetExists ( $offset )

offsetGet() public méthode

public offsetGet ( $offset )

offsetSet() public méthode

public offsetSet ( $offset, $value )

offsetUnset() public méthode

public offsetUnset ( $offset )

queueFilter() public méthode

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 méthode

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 méthode

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

renameColumn() public méthode

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 méthode

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

setLabelsHaveChanged() public méthode

setMaximumAllowedRows() public méthode

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 méthode

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 méthode

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

setMetadataValues() public méthode

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

setRows() public méthode

public setRows ( $rows )

setTableSortedBy() public méthode

public setTableSortedBy ( $column )

sort() public méthode

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 méthode

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.
Résultat 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_oe property

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

$depthLevel protected_oe property

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

$disabledFilters protected_oe property

List of disabled filter names eg 'Limit' or 'Sort'
protected array $disabledFilters
Résultat array

$enableRecursiveFilters protected_oe 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
Résultat boolean

$enableRecursiveSort protected_oe 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
Résultat boolean

$indexNotUpToDate protected_oe property

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

$maximumAllowedRows protected_oe property

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

$queuedFilters protected_oe property

List of BaseFilter queued to this table
protected array $queuedFilters
Résultat array

$rebuildIndexContinuously protected_oe 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
Résultat boolean

$rows protected_oe property

Array of Row
protected Row[],Piwik\DataTable $rows
Résultat Piwik\DataTable\Row[]

$rowsCountBeforeLimitFilter protected_oe property

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

$rowsIndexByLabel protected_oe property

protected array $rowsIndexByLabel
Résultat array

$summaryRow protected_oe property

protected Row,Piwik\DataTable $summaryRow
Résultat Piwik\DataTable\Row

$tableSortedBy protected_oe property

Column name of last time the table was sorted
protected string $tableSortedBy
Résultat string