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

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 Matomo (formerly 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.
  • 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 is the summary row, false if otherwise.
  • isEqual() — Helper function that tests if two rows are equal.

__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: booltrue 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.

getColumn()

Returns a column by name.

Signature

  • It accepts the following parameter(s):

    • $name (string) — The column name.
  • Returns: mixed|Piwik\DataTable\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

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.

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 Matomo\DataTable\Manager.

Signature

  • It returns a bool value.

removeSubtable()

Removes the subtable reference.

Signature

  • It does not return anything.

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.

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.

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.

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: booltrue 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.
  • 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.
  • 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.
  • It throws one of the following exceptions:

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.

isSummaryRow()

Returns true if this row is the summary row, false if otherwise.

This function depends on the label of the row, and so, is not 100% accurate.

Signature

  • It returns a bool value.

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.