DataTable.php

<?php
/**
 * Piwik - Open source web analytics
 *
 * @link http://piwik.org
 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 *
 * @category Piwik
 * @package Piwik
 */

namespace Piwik;

use Closure;
use Exception;
use Piwik\DataTable\DataTableInterface;
use Piwik\DataTable\Filter;
use Piwik\DataTable\Manager;
use Piwik\DataTable\Renderer\Html;
use Piwik\DataTable\Row;
use Piwik\DataTable\Row\DataTableSummaryRow;
use ReflectionClass;

/**
 * @see Common::destroy()
 */
require_once PIWIK_INCLUDE_PATH . '/core/Common.php';

/**
 * The primary data structure used to store analytics data in Piwik.
 * 
 * ### The Basics
 * 
 * DataTables consist of rows and each row consists of columns. A column value can be
 * be a numeric, string or array.
 * 
 * DataTables are hierarchical data structures. Each row can also contain an additional
 * nested sub-DataTable.
 * 
 * Both DataTables and DataTable rows can hold **metadata**. _DataTable metadata_ is information
 * regarding all the data, such as the site or period that the data is for. _Row metadata_
 * is information regarding that row, such as a browser logo or website URL.
 * 
 * Finally, DataTables all contain a special _summary_ row.
 * 
 * ### Populating DataTables
 * 
 * Data can be added to DataTables in a couple different ways. You can either:
 * 
 * 1. create rows one by one and add them through [addRow](#addRow) then truncate if desired,
 * 2. create an array of DataTable\Row instances or an array of arrays and add them using
 *    [addRowsFromArray](#addRowsFromArray) or [addRowsFromSimpleArray](#addRowsFromSimpleArray)
 *    then truncate if desired,
 * 3. or set the maximum number of allowed rows (with [setMaximumAllowedRows](#setMaximumAllowedRows))
 *    and add rows one by one.
 * 
 * If you want to eventually truncate your data (standard practice for all Piwik plugins),
 * the third method is the most memory efficient. It is, unfortunately, not always possible
 * to use since it requires that the data be sorted before adding.
 * 
 * ### Manipulating DataTables
 * 
 * There are two main ways to manipulate a DataTable. You can either:
 * 
 * 1. manually iterate through each row and manipulate the data,
 * 2. or you can use predefined Filters.
 * 
 * A Filter is a class that has a 'filter' method which will manipulate a DataTable in
 * some way. There are several predefined Filters that allow you to do common things,
 * such as,
 * 
 * - add a new column to each row,
 * - add new metadata to each row,
 * - modify an existing column value for each row,
 * - sort an entire DataTable,
 * - and more.
 * 
 * Using these Filters instead of writing your own code will increase code clarity and
 * reduce code redundancy. Additionally, Filters have the advantage that they can be
 * applied to DataTable\Map instances. So you can visit every DataTable in a DataTable\Map
 * without having to write a recursive visiting function.
 * 
 * Note: Anonymous functions can be used as DataTable Filters.
 * 
 * ### Applying Filters
 * 
 * Filters can be applied now (via [filter](#filter)), or they can be applied later (via
 * [queueFilter](#queueFilter)).
 * 
 * Filters that sort rows or manipulate the number of rows should be applied right away.
 * Non-essential, presentation filters should be queued.
 * 
 * See also:
 * 
 * - ArchiveProcessor &mdash; to learn how DataTables are persisted.
 * - DataTable\Renderer &mdash; to learn how DataTable data is exported to XML, JSON, etc.
 * - DataTable\Filter &mdash; to see all core Filters.
 * - DataTable\Manager &mdash; to learn how DataTables are loaded.
 * 
 * ### Examples
 * 
 * **Populating a DataTable**
 * **Serializing & unserializing**
 * **Filtering for an API method**
 * ??? TODO
 * 
 * @package Piwik
 * @subpackage DataTable
 *
 * @api
 */
class DataTable implements DataTableInterface
{
    /** Name for metadata that describes when a report was archived. */
    const ARCHIVED_DATE_METADATA_NAME = 'archived_date';
    const MAX_DEPTH_DEFAULT = 15;
    /** Name for metadata that describes which columns are empty and should not be shown. */
    const EMPTY_COLUMNS_METADATA_NAME = 'empty_column';

    /**
     * Maximum nesting level.
     */
    private static $maximumDepthLevelAllowed = self::MAX_DEPTH_DEFAULT;

    /**
     * Array of Row
     *
     * @var Row[]
     */
    protected $rows = array();

    /**
     * Id assigned to the DataTable, used to lookup the table using the DataTable_Manager
     *
     * @var int
     */
    protected $currentId;

    /**
     * Current depth level of this data table
     * 0 is the parent data table
     *
     * @var int
     */
    protected $depthLevel = 0;

    /**
     * This flag is set to false once we modify the table in a way that outdates the index
     *
     * @var bool
     */
    protected $indexNotUpToDate = true;

    /**
     * This flag sets the index to be rebuild whenever a new row is added,
     * as opposed to re-building the full index when getRowFromLabel is called.
     * This is to optimize and not rebuild the full Index in the case where we
     * add row, getRowFromLabel, addRow, getRowFromLabel thousands of times.
     *
     * @var bool
     */
    protected $rebuildIndexContinuously = false;

    /**
     * Column name of last time the table was sorted
     *
     * @var string
     */
    protected $tableSortedBy = false;

    /**
     * List of Filter queued to this table
     *
     * @var array
     */
    protected $queuedFilters = array();

    /**
     * We keep track of the number of rows before applying the LIMIT filter that deletes some rows
     *
     * @var int
     */
    protected $rowsCountBeforeLimitFilter = 0;

    /**
     * Defaults to false for performance reasons (most of the time we don't need recursive sorting so we save a looping over the dataTable)
     *
     * @var bool
     */
    protected $enableRecursiveSort = false;

    /**
     * When the table and all subtables are loaded, this flag will be set to true to ensure filters are applied to all subtables
     *
     * @var bool
     */
    protected $enableRecursiveFilters = false;

    /**
     * @var array