API Reference

Map

Piwik\DataTable\

Map

Stores an array of DataTables indexed by one type of DataTable metadata (such as site ID or period).

DataTable Maps are returned on all queries that involve multiple sites and/or multiple periods. The Maps will contain a DataTable for each site and period combination.

The Map implements some DataTable such as queueFilter() and getRowsCount.

Methods

The class defines the following methods:

  • getKeyName() — Returns a string description of the data used to index the DataTables.
  • setKeyName() — Set the name of they metadata used to index DataTables.
  • getRowsCount() — Returns the number of DataTables in this DataTable\Map.
  • queueFilter() — Queue a filter to DataTable child of contained by this instance.
  • applyQueuedFilters() — Apply the filters previously queued to each DataTable contained by this DataTable\Map.
  • filter() — Apply a filter to all tables contained by this instance.
  • multiFilter() — Apply a callback to all tables contained by this instance and tables with the same key in $otherTables.
  • filterSubtables() — Apply a filter to all subtables contained by this instance.
  • queueFilterSubtables() — Apply a queued filter to all subtables contained by this instance.
  • getDataTables() — Returns the array of DataTables contained by this class.
  • getTable() — Returns the table with the specific label.
  • hasTable()
  • getFirstRow() — Returns the first element in the Map's array.
  • getLastRow() — Returns the last element in the Map's array.
  • addTable() — Adds a new DataTable or Map instance to this DataTable\Map.
  • getRowFromIdSubDataTable()
  • __toString() — Returns a string output of this DataTable\Map (applying the default renderer to every DataTable of this DataTable\Map).
  • enableRecursiveSort() — See DataTable::enableRecursiveSort().
  • disableFilter() — See DataTable::disableFilter().
  • renameColumn() — Renames the given column in each contained DataTable.
  • deleteColumns() — Deletes the specified columns in each contained DataTable.
  • deleteRow() — Deletes a table from the array of DataTables.
  • deleteColumn() — Deletes the given column in every contained DataTable.
  • getColumn() — Returns the array containing all column values in all contained DataTables for the requested column.
  • mergeChildren() — Merges the rows of every child DataTable into a new one and returns it.
  • addDataTable() — Sums a DataTable to all the tables in this array.
  • mergeSubtables() — Returns a new DataTable\Map w/ child tables that have had their subtables merged.
  • getEmptyClone() — Returns a new DataTable\Map w/o any child DataTables, but with the same key name as this instance.
  • getMetadataIntersectArray() — Returns the intersection of children's metadata arrays (what they all have in common).
  • deleteRowsMetadata() — Delete row metadata by name in every row.
  • getColumns() — See DataTable::getColumns().

getKeyName()

Returns a string description of the data used to index the DataTables.

This label is used by DataTable Renderers (it becomes a column name or the XML description tag).

Signature

  • Returns: string — eg, 'idSite', 'period'

setKeyName()

Set the name of they metadata used to index DataTables. See getKeyName().

Signature

  • It accepts the following parameter(s):

    • $name (string) —

  • It does not return anything or a mixed result.

getRowsCount()

Returns the number of DataTables in this DataTable\Map.

Signature

  • It returns a int value.

queueFilter()

Queue a filter to DataTable child of contained by this instance.

See DataTable::queueFilter() for more information..

Signature

  • It accepts the following parameter(s):
    • $className (string|Closure) — Filter name, eg. 'Limit' or a Closure.
    • $parameters (array) — Filter parameters, eg. array(50, 10).
  • It does not return anything or a mixed result.

applyQueuedFilters()

Apply the filters previously queued to each DataTable contained by this DataTable\Map.

Signature

  • It does not return anything or a mixed result.

filter()

Apply a filter to all tables contained by this instance.

Signature

  • It accepts the following parameter(s):
    • $className (string|Closure) — Name of filter class or a Closure.
    • $parameters (array) — Parameters to pass to the filter.
  • It does not return anything or a mixed result.

multiFilter()

Apply a callback to all tables contained by this instance and tables with the same key in $otherTables.

This method is used to iterate over multiple DataTable\Map's concurrently.

$filter will be called with multiple DataTable instances, the first is the instance contained in this Map instance. The rest are the corresponding instances found in $otherTables. The position of the parameter in $filter corresponds with the position in $otherTables.

If a key exists in this instance but not in one of the otherTables, $filter will be invoked with null for that parameter.

Signature

  • It accepts the following parameter(s):

    • $otherTables (Map[]) — Other tables to invoke $filter with.
    • $filter (callable) — A function like function (DataTable $thisTable, $otherTable1, $otherTable2, ...) {}.

  • Returns: mixed[] — The return value of each multiFilter() call made on child tables, indexed by the keys in this Map instance.

filterSubtables()

Apply a filter to all subtables contained by this instance.

Signature

  • It accepts the following parameter(s):
    • $className (string|Closure) — Name of filter class or a Closure.
    • $parameters (array) — Parameters to pass to the filter.
  • It does not return anything or a mixed result.

queueFilterSubtables()

Apply a queued filter to all subtables contained by this instance.

Signature

  • It accepts the following parameter(s):
    • $className (string|Closure) — Name of filter class or a Closure.
    • $parameters (array) — Parameters to pass to the filter.
  • It does not return anything or a mixed result.

getDataTables()

Returns the array of DataTables contained by this class.

Signature

getTable()

Returns the table with the specific label.

Signature

  • It accepts the following parameter(s):

    • $label (string) —

  • Returns: DataTable|Map —

hasTable()

Signature

  • It accepts the following parameter(s):

    • $label (string) —

  • It returns a bool value.

getFirstRow()

Returns the first element in the Map's array.

Signature

getLastRow()

Returns the last element in the Map's array.

Signature

addTable()

Adds a new DataTable or Map instance to this DataTable\Map.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable|Map) —

    • $label (string) — Label used to index this table in the array.

  • It does not return anything or a mixed result.

getRowFromIdSubDataTable()

Signature

  • It accepts the following parameter(s):

    • $idSubtable

  • It does not return anything or a mixed result.

__toString()

Returns a string output of this DataTable\Map (applying the default renderer to every DataTable of this DataTable\Map).

Signature

  • It returns a string value.

enableRecursiveSort()

See DataTable::enableRecursiveSort().

Signature

  • It does not return anything or a mixed result.

disableFilter()

See DataTable::disableFilter().

Signature

  • It accepts the following parameter(s):

    • $className

  • It does not return anything or a mixed result.

renameColumn()

Renames the given column in each contained DataTable.

See DataTable::renameColumn().

Signature

  • It accepts the following parameter(s):

    • $oldName (string) —

    • $newName (string) —

  • It does not return anything or a mixed result.

deleteColumns()

Deletes the specified columns in each contained DataTable.

See DataTable::deleteColumns().

Signature

  • It accepts the following parameter(s):
    • $columns (array) — The columns to delete.
    • $deleteRecursiveInSubtables (bool) — This param is currently not used.
  • It does not return anything or a mixed result.

deleteRow()

Deletes a table from the array of DataTables.

Signature

  • It accepts the following parameter(s):
    • $id (string) — The label associated with DataTable.
  • It does not return anything or a mixed result.

deleteColumn()

Deletes the given column in every contained DataTable.

See Also

  • DataTable::deleteColumn

Signature

  • It accepts the following parameter(s):

    • $name (string) —

  • It does not return anything or a mixed result.

getColumn()

Returns the array containing all column values in all contained DataTables for the requested column.

Signature

  • It accepts the following parameter(s):
    • $name (string) — The column name.
  • It returns a array value.

mergeChildren()

Merges the rows of every child DataTable into a new one and returns it. This function will also set the label of the merged rows to the label of the DataTable they were originally from.

The result of this function is determined by the type of DataTable this instance holds. If this DataTable\Map instance holds an array of DataTables, this function will transform it from:

Label 0:
  DataTable(row1)
Label 1:
  DataTable(row2)

to:

DataTable(row1[label = 'Label 0'], row2[label = 'Label 1'])

If this instance holds an array of DataTable\Maps, this function will transform it from:

Outer Label 0:            // the outer DataTable\Map
  Inner Label 0:            // one of the inner DataTable\Maps
    DataTable(row1)
  Inner Label 1:
    DataTable(row2)
Outer Label 1:
  Inner Label 0:
    DataTable(row3)
  Inner Label 1:
    DataTable(row4)

to:

Inner Label 0:
  DataTable(row1[label = 'Outer Label 0'], row3[label = 'Outer Label 1'])
Inner Label 1:
  DataTable(row2[label = 'Outer Label 0'], row4[label = 'Outer Label 1'])

If this instance holds an array of DataTable\Maps, the metadata of the first child is used as the metadata of the result.

This function can be used, for example, to smoosh IndexedBySite archive query results into one DataTable w/ different rows differentiated by site ID.

Note: This DataTable/Map will be destroyed and will be no longer usable after the tables have been merged into the new dataTable to reduce memory usage. Destroying all DataTables within the Map also seems to fix a Segmentation Fault that occurred in the AllWebsitesDashboard when having > 16k sites.

Signature

addDataTable()

Sums a DataTable to all the tables in this array.

Note: Will only add $tableToSum if the childTable has some rows.

See DataTable::addDataTable().

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

mergeSubtables()

Returns a new DataTable\Map w/ child tables that have had their subtables merged.

See DataTable::mergeSubtables().

Signature

  • It returns a Map value.

getEmptyClone()

Returns a new DataTable\Map w/o any child DataTables, but with the same key name as this instance.

Signature

  • It returns a Map value.

getMetadataIntersectArray()

Returns the intersection of children's metadata arrays (what they all have in common).

Signature

  • It accepts the following parameter(s):
    • $name (string) — The metadata name.
  • It returns a mixed value.

deleteRowsMetadata()

Delete row metadata by name in every row.

Signature

  • It accepts the following parameter(s):

    • $name

    • $deleteRecursiveInSubtables (bool) —

  • It does not return anything or a mixed result.

getColumns()

See DataTable::getColumns().

Signature

  • It returns a array value.