DataTable.php

     * Each row of this returned PHP array will be a row in the DB table.
     * At the end of the method execution, the dataTable may be truncated (if $maximum* parameters are set).
     *
     * The keys of the array are very important as they are used to define the DataTable
     *
     * IMPORTANT: The main table (level 0, parent of all tables) will always be indexed by 0
     *    even it was created after some other tables.
     *    It also means that all the parent tables (level 0) will be indexed with 0 in their respective
     *  serialized arrays. You should never lookup a parent table using the getTable( $id = 0) as it
     *  won't work.
     *
     * @throws Exception if an infinite recursion is found (a table row's has a subtable that is one of its parent table)
     * @param int $maximumRowsInDataTable          If not null, defines the number of rows maximum of the serialized dataTable
     * @param int $maximumRowsInSubDataTable       If not null, defines the number of rows maximum of the serialized subDataTable
     * @param string $columnToSortByBeforeTruncation  Column to sort by before truncation
     * @return array  Serialized arrays
     *            array(    // Datatable level0
     *                    0 => 'eghuighahgaueytae78yaet7yaetae',
     *
     *                    // first Datatable level1
     *                    1 => 'gaegae gh gwrh guiwh uigwhuige',
     *
     *                    //second Datatable level1
     *                    2 => 'gqegJHUIGHEQjkgneqjgnqeugUGEQHGUHQE',
     *
     *                    //first Datatable level3 (child of second Datatable level1 for example)
     *                    3 => 'eghuighahgaueytae78yaet7yaetaeGRQWUBGUIQGH&QE',
     *                    );
     */
    public function getSerialized($maximumRowsInDataTable = null,
                                  $maximumRowsInSubDataTable = null,
                                  $columnToSortByBeforeTruncation = null)
    {
        static $depth = 0;

        if ($depth > self::$maximumDepthLevelAllowed) {
            $depth = 0;
            throw new Exception("Maximum recursion level of " . self::$maximumDepthLevelAllowed . " reached. Maybe you have set a DataTable\Row with an associated DataTable belonging already to one of its parent tables?");
        }
        if (!is_null($maximumRowsInDataTable)) {
            $this->filter('AddSummaryRow',
                array($maximumRowsInDataTable - 1,
                      DataTable::LABEL_SUMMARY_ROW,
                      $columnToSortByBeforeTruncation)
            );
        }

        // For each row, get the serialized row
        // If it is associated to a sub table, get the serialized table recursively ;
        // but returns all serialized tables and subtable in an array of 1 dimension
        $aSerializedDataTable = array();
        foreach ($this->rows as $row) {
            if (($idSubTable = $row->getIdSubDataTable()) !== null) {
                $subTable = Manager::getInstance()->getTable($idSubTable);
                $depth++;
                $aSerializedDataTable = $aSerializedDataTable + $subTable->getSerialized($maximumRowsInSubDataTable, $maximumRowsInSubDataTable, $columnToSortByBeforeTruncation);
                $depth--;
            }
        }
        // we load the current Id of the DataTable
        $forcedId = $this->getId();

        // if the datatable is the parent we force the Id at 0 (this is part of the specification)
        if ($depth == 0) {
            $forcedId = 0;
        }

        // we then serialize the rows and store them in the serialized dataTable
        $addToRows = array(self::ID_SUMMARY_ROW => $this->summaryRow);

        $aSerializedDataTable[$forcedId] = serialize($this->rows + $addToRows);
        foreach ($this->rows as &$row) {
            $row->cleanPostSerialize();
        }

        return $aSerializedDataTable;
    }

    /**
     * Load a serialized string of a datatable.
     *
     * Does not load recursively all the sub DataTable.
     * They will be loaded only when requesting them specifically.
     *
     * The function creates all the necessary DataTable\Row
     *
     * @param string $stringSerialized  string of serialized datatable
     * @throws Exception
     */
    public function addRowsFromSerializedArray($stringSerialized)
    {
        $serialized = unserialize($stringSerialized);
        if ($serialized === false) {
            throw new Exception("The unserialization has failed!");
        }
        $this->addRowsFromArray($serialized);
    }

    /**
     * Loads the DataTable from a PHP array data structure
     *
     * @param 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( ... ),
     *                       )
     */
    public function addRowsFromArray($array)
    {
        foreach ($array as $id => $row) {
            if (is_array($row)) {
                $row = new Row($row);
            }
            if ($id == self::ID_SUMMARY_ROW) {
                $this->summaryRow = $row;
            } else {
                $this->addRow($row);
            }
        }
    }

    /**
     * Loads the data from a simple php array.
     * Basically maps a simple multidimensional php array to a DataTable.
     * Not recursive (if a row contains a php array itself, it won't be loaded)
     *
     * @param array $array  Array with the simple structure:
     *                       array(
     *                             array( col1_name => valueA, col2_name => valueC, ...),
     *                             array( col1_name => valueB, col2_name => valueD, ...),
     *                       )
     * @throws Exception
     * @return void
     */
    public function addRowsFromSimpleArray($array)
    {
        if (count($array) === 0) {
            return;
        }

        // we define an exception we may throw if at one point we notice that we cannot handle the data structure
        $e = new Exception(" Data structure returned is not convertible in the requested format." .
            " Try to call this method with the parameters '&format=original&serialize=1'" .
            "; you will get the original php data structure serialized." .
            " The data structure looks like this: \n \$data = " . var_export($array, true) . "; ");

        // first pass to see if the array has the structure
        // array(col1_name => val1, col2_name => val2, etc.)
        // with val* that are never arrays (only strings/numbers/bool/etc.)
        // if we detect such a "simple" data structure we convert it to a row with the correct columns' names
        $thisIsNotThatSimple = false;

        foreach ($array as $columnValue) {
            if (is_array($columnValue) || is_object($columnValue)) {
                $thisIsNotThatSimple = true;
                break;
            }
        }
        if ($thisIsNotThatSimple === false) {
            // case when the array is indexed by the default numeric index
            if (array_keys($array) == array_keys(array_fill(0, count($array), true))) {
                foreach ($array as $row) {
                    $this->addRow(new Row(array(Row::COLUMNS => array($row))));
                }
            } else {
                $this->addRow(new Row(array(Row::COLUMNS => $array)));
            }
            // we have converted our simple array to one single row
            // => we exit the method as the job is now finished
            return;
        }

        foreach ($array as $key => $row) {
            // stuff that looks like a line
            if (is_array($row)) {
                /**
                 * We make sure we can convert this PHP array without losing information.
                 * We are able to convert only simple php array (no strings keys, no sub arrays, etc.)
                 *
                 */

                // if the key is a string it means that some information was contained in this key.
                // it cannot be lost during the conversion. Because we are not able to handle properly
                // this key, we throw an explicit exception.
                if (is_string($key)) {
                    throw $e;
                }
                // if any of the sub elements of row is an array we cannot handle this data structure...
                foreach ($row as $subRow) {
                    if (is_array($subRow)) {
                        throw $e;
                    }
                }
                $row = new Row(array(Row::COLUMNS => $row));
            } // other (string, numbers...) => we build a line from this value
            else {
                $row = new Row(array(Row::COLUMNS => array($key => $row)));
            }
            $this->addRow($row);
        }
    }

    /**
     * Rewrites the input $array
     * array (
     *     LABEL => array(col1 => X, col2 => Y),
     *     LABEL2 => array(col1 => X, col2 => Y),
     * )
     * to a DataTable, ie. with the internal structure
     * array (
     *     array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)),
     *     array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)),
     * )
     *
     * It also works with array having only one value per row, eg.
     * array (
     *     LABEL => X,
     *     LABEL2 => Y,
     * )
     * would be converted to:
     * array (
     *     array( Row::COLUMNS => array('label' => LABEL, 'value' => X)),
     *     array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)),
     * )
     *
     *
     * @param array $array Indexed array, two formats are supported
     * @param array|null $subtablePerLabel An indexed array of up to one DataTable to associate as a sub table
     * @return \Piwik\DataTable
     */
    public static function makeFromIndexedArray($array, $subtablePerLabel = null)
    {
        $table = new DataTable();
        $cleanRow = array();
        foreach ($array as $label => $row) {
            // Support the case of an $array of single values
            if (!is_array($row)) {
                $row = array('value' => $row);
            }
            // Put the 'label' column first
            $cleanRow[Row::COLUMNS] = array('label' => $label) + $row;
            // Assign subtable if specified
            if (isset($subtablePerLabel[$label])) {
                $cleanRow[Row::DATATABLE_ASSOCIATED] = $subtablePerLabel[$label];
            }
            $table->addRow(new Row($cleanRow));
        }
        return $table;
    }

    /**
     * Sets the maximum nesting level to at least a certain value. If the current value is
     * greater than the supplied level, the maximum nesting level is not changed.
     *
     * @param int $atLeastLevel
     */
    public static function setMaximumDepthLevelAllowedAtLeast($atLeastLevel)
    {
        self::$maximumDepthLevelAllowed = max($atLeastLevel, self::$maximumDepthLevelAllowed);
        if (self::$maximumDepthLevelAllowed < 1) {
            self::$maximumDepthLevelAllowed = 1;
        }
    }

    /**
     * Returns all table metadata.
     *
     * @return array
     */
    public function getAllTableMetadata()
    {
        return $this->metadata;
    }

    /**
     * Returns metadata by name.
     *
     * @param string $name The metadata name.
     * @return mixed
     */
    public function getMetadata($name)
    {
        if (!isset($this->metadata[$name])) {
            return false;
        }
        return $this->metadata[$name];
    }

    /**
     * Sets a metadata value by name.
     *
     * @param string $name The metadata name.
     * @param mixed $value
     */
    public function setMetadata($name, $value)
    {
        $this->metadata[$name] = $value;
    }

    /**
     * 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 added to the summary row.
     *
     * @param int|null $maximumAllowedRows
     */
    public function setMaximumAllowedRows($maximumAllowedRows)
    {
        $this->maximumAllowedRows = $maximumAllowedRows;
    }

    /**
     * Traverses a DataTable tree using an array of labels and returns the row
     * it finds or false if it cannot find one, and the number of segments of
     * the path successfully walked.
     * If $missingRowColumns is supplied, the specified path is created. When
     * a subtable is encountered w/o the queried label, a new row is created
     * with the label, and a subtable is added to the row.
     *
     * @param array $path            The path to walk. An array of label values.
     * @param array|bool $missingRowColumns
     *                                      The default columns to use when creating new arrays.
     *                                      If this parameter is supplied, new rows will be
     *                                      created if labels cannot be found.
     * @param int $maxSubtableRows The maximum number of allowed rows in new
     *                                      subtables.
     *
     * @return 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.
     */
    public function walkPath($path, $missingRowColumns = false, $maxSubtableRows = 0)
    {
        $pathLength = count($path);

        $table = $this;
        $next = false;
        for ($i = 0; $i < $pathLength; ++$i) {
            $segment = $path[$i];

            $next = $table->getRowFromLabel($segment);
            if ($next === false) {
                // if there is no table to advance to, and we're not adding missing rows, return false
                if ($missingRowColumns === false) {
                    return array(false, $i);
                } else // if we're adding missing rows, add a new row
                {
                    $row = new DataTableSummaryRow();
                    $row->setColumns(array('label' => $segment) + $missingRowColumns);

                    $next = $table->addRow($row);

                    if ($next !== $row) // if the row wasn't added, the table is full
                    {
                        // Summary row, has no metadata
                        $next->deleteMetadata();
                        return array($next, $i);
                    }
                }
            }

            $table = $next->getSubtable();
            if ($table === false) {
                // if the row has no table (and thus no child rows), and we're not adding
                // missing rows, return false
                if ($missingRowColumns === false) {
                    return array(false, $i);
                } else if ($i != $pathLength - 1) // create subtable if missing, but only if not on the last segment
                {
                    $table = new DataTable();
                    $table->setMaximumAllowedRows($maxSubtableRows);
                    $table->setColumnAggregationOperations($this->columnAggregationOperations);
                    $next->setSubtable($table);
                    // Summary row, has no metadata
                    $next->deleteMetadata();
                }
            }
        }

        return array($next, $i);
    }

    /**
     * Returns a new DataTable that contains the rows of each of this table's subtables.
     *
     * @param string|bool $labelColumn       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.
     * @param bool $useMetadataColumn If true and if $labelColumn is supplied, the parent row's
     *                                        label will be added as metadata.
     *
     * @return \Piwik\DataTable
     */
    public function mergeSubtables($labelColumn = false, $useMetadataColumn = false)
    {
        $result = new DataTable();
        foreach ($this->getRows() as $row) {
            $subtable = $row->getSubtable();
            if ($subtable !== false) {
                $parentLabel = $row->getColumn('label');

                // add a copy of each subtable row to the new datatable
                foreach ($subtable->getRows() as $id => $subRow) {
                    $copy = clone $subRow;

                    // if the summary row, add it to the existing summary row (or add a new one)
                    if ($id == self::ID_SUMMARY_ROW) {
                        $existing = $result->getRowFromId(self::ID_SUMMARY_ROW);
                        if ($existing === false) {
                            $result->addSummaryRow($copy);
                        } else {
                            $existing->sumRow($copy, $copyMeta = true, $this->columnAggregationOperations);
                        }
                    } else {
                        if ($labelColumn !== false) {
                            // if we're modifying the subtable's rows' label column, then we make
                            // sure to prepend the existing label w/ the parent row's label. otherwise
                            // we're just adding the parent row's label as a new column/metadata.
                            $newLabel = $parentLabel;
                            if ($labelColumn == 'label') {
                                $newLabel .= ' - ' . $copy->getColumn('label');
                            }

                            // modify the child row's label or add new column/metadata
                            if ($useMetadataColumn) {
                                $copy->setMetadata($labelColumn, $newLabel);
                            } else {
                                $copy->setColumn($labelColumn, $newLabel);
                            }
                        }

                        $result->addRow($copy);
                    }
                }
            }
        }
        return $result;
    }

    /**
     * Returns a new DataTable created with data from a 'simple' array.
     *
     * @param array $array
     * @return \Piwik\DataTable
     */
    public static function makeFromSimpleArray($array)
    {
        $dataTable = new DataTable();
        $dataTable->addRowsFromSimpleArray($array);
        return $dataTable;
    }

    /**
     * Set the aggregation operation for a column, e.g. "min".
     * @see self::addDataTable() and DataTable\Row::sumRow()
     *
     * @param string $columnName
     * @param string $operation
     */
    public function setColumnAggregationOperation($columnName, $operation)
    {
        $this->columnAggregationOperations[$columnName] = $operation;
    }

    /**
     * Set multiple aggregation operations at once.
     * @param array $operations  format: column name => operation
     */
    public function setColumnAggregationOperations($operations)
    {
        foreach ($operations as $columnName => $operation) {
            $this->setColumnAggregationOperation($columnName, $operation);
        }
    }

    /**
     * Get the configured column aggregation operations
     */
    public function getColumnAggregationOperations()
    {
        return $this->columnAggregationOperations;
    }

    /**
     * Creates a new DataTable instance from a serialize()'d array of rows.
     *
     * @param string $data
     * @return \Piwik\DataTable
     */
    public static function fromSerializedArray($data)
    {
        $result = new DataTable();
        $result->addRowsFromSerializedArray($data);
        return $result;
    }
}