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
 */

use Piwik\Common;

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

/**
 *
 * ---- DataTable
 * A DataTable is a data structure used to store complex tables of data.
 *
 * A DataTable is composed of multiple DataTable_Row.
 * A DataTable can be applied one or several DataTable_Filter.
 * A DataTable can be given to a DataTable_Renderer that would export the data under a given format (XML, HTML, etc.).
 *
 * A DataTable has the following features:
 * - serializable to be stored in the DB
 * - loadable from the serialized version
 * - efficient way of loading data from an external source (from a PHP array structure)
 * - very simple interface to get data from the table
 *
 * ---- DataTable_Row
 * A DataTableRow in the table is defined by
 * - multiple columns (a label, multiple values, ...)
 * - optional metadata
 * - optional - a sub DataTable associated to this row
 *
 * Simple row example:
 * - columns = array(   'label' => 'Firefox',
 *                        'visitors' => 155,
 *                        'pages' => 214,
 *                        'bounce_rate' => 67)
 * - metadata = array('logo' => '/plugins/UserSettings/images/browsers/FF.gif')
 * - no sub DataTable
 *
 * A more complex example would be a DataTable_Row that is associated to a sub DataTable.
 * For example, for the row of the search engine Google,
 * we want to get the list of keywords associated, with their statistics.
 * - columns = array(   'label' => 'Google',
 *                        'visits' => 1550,
 *                        'visits_length' => 514214,
 *                        'returning_visits' => 77)
 * - metadata = array(    'logo' => '/plugins/Referers/images/searchEngines/google.com.png',
 *                        'url' => 'http://google.com')
 * - DataTable = DataTable containing several DataTable_Row containing the keywords information for this search engine
 *            Example of one DataTable_Row
 *            - the keyword columns specific to this search engine =
 *                    array(  'label' => 'Piwik', // the keyword
 *                            'visitors' => 155,  // Piwik has been searched on Google by 155 visitors
 *                            'pages' => 214 // Visitors coming from Google with the kwd Piwik have seen 214 pages
 *                    )
 *            - the keyword metadata = array() // nothing here, but we could imagining storing the URL of the search in Google for example
 *            - no subTable
 *
 *
 * ---- DataTable_Filter
 * A DataTable_Filter is a applied to a DataTable and so
 * can filter information in the multiple DataTable_Row.