Piwik\DataTable\

Row

This is what a DataTable is composed of.

DataTable rows contain columns, metadata and a subtable ID. Columns and metadata are stored as an array of name => value mappings.

Properties

This class defines the following properties:

• $maxVisitsSummed
• $subtableId

$maxVisitsSummed

Signature

• Its type is not specified.

$subtableId

Signature

• Its type is not specified.

Methods

The class defines the following methods:

• __construct() — Constructor.
• __toString() — Applies a basic rendering to the Row and returns the output.
• deleteColumn() — Deletes the given column.
• renameColumn() — Renames a column.
• getColumn() — Returns a column by name.
• getMetadata() — Returns the array of all metadata, or one requested metadata value.
• hasColumn() — Returns true if a column having the given name is already registered.
• getColumns() — Returns the array containing all the columns.
• getIdSubDataTable() — Returns the ID of the subDataTable.
• getSubtable() — Returns the associated subtable, if one exists.
• sumSubtable() — Sums a DataTable to this row's subtable.
• setSubtable() — Attaches a subtable to this row, overwriting the existing subtable, if any.
• isSubtableLoaded() — Returns true if the subtable is currently loaded in memory via Piwik\DataTable\Manager.
• removeSubtable() — Removes the subtable reference.
• setColumns() — Set all the columns at once.
• setColumn() — Set the value $value to the column called $name.
• setMetadata() — Set the value $value to the metadata called $name.
• setAllMetadata() — Sets all metadata at once.
• deleteMetadata() — Deletes one metadata value or all metadata values.
• addColumn() — Add a new column to the row.
• addColumns() — Add many columns to this row.
• addMetadata() — Add a new metadata to the row.
• sumRow() — Sums the given $rowToSum columns values to the existing row column values.
• sumRowMetadata() — Sums the metadata in $rowToSum with the metadata in $this row.
• isSummaryRow() — Returns true if this row was added to a datatable as the summary row, false if otherwise.
• setIsSummaryRow()
• getComparisons() — Returns the associated comparisons DataTable, if any.
• setComparisons() — Associates the supplied table with this row as the comparisons table.
• isEqual() — Helper function that tests if two rows are equal.
• sumRowWithLabelToSubtable()

__construct()

Constructor.

Signature

• It accepts the following parameter(s):
  • $row (array) — An array with the following structure: array( Row::COLUMNS => array('label' => 'Matomo', 'column1' => 42, 'visits' => 657, 'time_spent' => 155744), Row::METADATA => array('logo' => 'test.png'), Row::DATATABLE_ASSOCIATED => $subtable // DataTable object // (but in the row only the ID will be stored) )

__toString()

Applies a basic rendering to the Row and returns the output.

Signature

• Returns: string — describing the row. Example: "- 1 ['label' => 'piwik', 'nb_uniq_visitors' => 1685, 'nb_visits' => 1861] [] [idsubtable = 1375]"

deleteColumn()

Deletes the given column.

Signature

• It accepts the following parameter(s):

  • $name (string) — The column name.

• Returns: bool — true on success, false if the column does not exist.

renameColumn()

Renames a column.

Signature

• It accepts the following parameter(s):
  • $oldName (string) — The current name of the column.
  • $newName (string) — The new name of the column.
• It does not return anything or a mixed result.

getColumn()

Returns a column by name.

Signature

• It accepts the following parameter(s):

  • $name (string|int) — The column name.

• Returns: mixed|false — The column value or false if it doesn't exist.

getMetadata()

Returns the array of all metadata, or one requested metadata value.

Signature

• It accepts the following parameter(s):
  • $name (string|null) — The name of the metadata to return or null to return all metadata.
• It returns a mixed value.

hasColumn()

Returns true if a column having the given name is already registered. The value will not be evaluated, it will just check whether a column exists independent of its value.

Signature

• It accepts the following parameter(s):

  • $name (string) —

• It returns a bool value.

getColumns()

Returns the array containing all the columns.

Signature

• Returns: array — Example:

             array(
                 'column1'   => VALUE,
                 'label'     => 'www.php.net'
                 'nb_visits' => 15894,
             )
  

getIdSubDataTable()

Returns the ID of the subDataTable.

If there is no such a table, returns null.

Signature

• Returns: int|null —

getSubtable()

Returns the associated subtable, if one exists. Returns false if none exists.

Signature

• Returns: DataTable|bool —

sumSubtable()

Sums a DataTable to this row's subtable. If this row has no subtable a new one is created.

See DataTable::addDataTable() to learn how DataTables are summed.

Signature

• It accepts the following parameter(s):
  • $subTable (DataTable) — Table to sum to this row's subtable.
• It does not return anything or a mixed result.

setSubtable()

Attaches a subtable to this row, overwriting the existing subtable, if any.

Signature

• It accepts the following parameter(s):

  • $subTable (DataTable) — DataTable to associate to this row.

• Returns: DataTable — Returns $subTable.

isSubtableLoaded()

Returns true if the subtable is currently loaded in memory via Piwik\DataTable\Manager.

Signature

• It returns a bool value.

removeSubtable()

Removes the subtable reference.

Signature

• It does not return anything or a mixed result.

setColumns()

Set all the columns at once. Overwrites all previously set columns.

Signature

• It accepts the following parameter(s):
  • $columns (array) — eg, array('label' => 'www.php.net', 'nb_visits' => 15894)
• It does not return anything or a mixed result.

setColumn()

Set the value $value to the column called $name.

Signature

• It accepts the following parameter(s):
  • $name (string) — name of the column to set.
  • $value (mixed) — value of the column to set.
• It does not return anything or a mixed result.

setMetadata()

Set the value $value to the metadata called $name.

Signature

• It accepts the following parameter(s):
  • $name (string) — name of the metadata to set.
  • $value (mixed) — value of the metadata to set.
• It does not return anything or a mixed result.

setAllMetadata()

Sets all metadata at once.

Signature

• It accepts the following parameter(s):
  • $metadata (array) — new metadata to set
• It does not return anything or a mixed result.

deleteMetadata()

Deletes one metadata value or all metadata values.

Signature

• It accepts the following parameter(s):

  • $name (bool|string) — Metadata name (omit to delete entire metadata).

• Returns: bool — true on success, false if the column didn't exist

addColumn()

Add a new column to the row. If the column already exists, throws an exception.

Signature

• It accepts the following parameter(s):
  • $name (string) — name of the column to add.
  • $value (mixed) — value of the column to set or a PHP callable.
• It does not return anything or a mixed result.
• It throws one of the following exceptions:
  • Exception — if the column already exists.

addColumns()

Add many columns to this row.

Signature

• It accepts the following parameter(s):
  • $columns (array) — Name/Value pairs, e.g., array('name' => $value , ...)
• It returns a void value.
• It throws one of the following exceptions:
  • Exception — if any column name does not exist.

addMetadata()

Add a new metadata to the row. If the metadata already exists, throws an exception.

Signature

• It accepts the following parameter(s):
  • $name (string) — name of the metadata to add.
  • $value (mixed) — value of the metadata to set.
• It does not return anything or a mixed result.
• It throws one of the following exceptions:
  • Exception — if the metadata already exists.

sumRow()

Sums the given $rowToSum columns values to the existing row column values.

Only the int or float values will be summed. Label columns will be ignored even if they have a numeric value.

Columns in $rowToSum that don't exist in $this are added to $this.

Signature

• It accepts the following parameter(s):
  • $rowToSum (Row) — The row to sum to this row.
  • $enableCopyMetadata (bool) — Whether metadata should be copied or not.
  • $aggregationOperations (array|bool) — for columns that should not be summed, determine which aggregation should be used (min, max). format: array('column name' => 'function name')
• It does not return anything or a mixed result.
• It throws one of the following exceptions:
  • Exception

sumRowMetadata()

Sums the metadata in $rowToSum with the metadata in $this row.

Signature

• It accepts the following parameter(s):

  • $rowToSum (Row) —

  • $aggregationOperations (array) —

• It does not return anything or a mixed result.

isSummaryRow()

Returns true if this row was added to a datatable as the summary row, false if otherwise.

Signature

• It returns a bool value.

setIsSummaryRow()

Signature

• It does not return anything or a mixed result.

getComparisons()

Returns the associated comparisons DataTable, if any.

Signature

• Returns: DataTable|null —

setComparisons()

Associates the supplied table with this row as the comparisons table.

Signature

• It accepts the following parameter(s):

  • $table (DataTable) —

• It does not return anything or a mixed result.

isEqual()

Helper function that tests if two rows are equal.

Two rows are equal if:

• they have exactly the same columns / metadata
• they have a subDataTable associated, then we check that both of them are the same.

Column order is not important.

Signature

• It accepts the following parameter(s):
  • $row1 (Row) — first to compare
  • $row2 (Row) — second to compare
• It returns a bool value.

sumRowWithLabelToSubtable()

Signature

• It accepts the following parameter(s):

  • $label (string) —

  • $columns (array) —

  • $aggregationOps (array|null) —

• It returns a Row value.