API Reference

Row

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.

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) — 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

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:

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

setComparisons()

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

Signature

  • It accepts the following parameter(s):

  • 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.