Teknik is a suite of services with attractive and functional interfaces. https://www.teknik.io/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

DataTable.php 57KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673
  1. <?php
  2. /**
  3. * Piwik - free/libre analytics platform
  4. *
  5. * @link http://piwik.org
  6. * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  7. *
  8. */
  9. namespace Piwik;
  10. use Closure;
  11. use Exception;
  12. use Piwik\DataTable\DataTableInterface;
  13. use Piwik\DataTable\Manager;
  14. use Piwik\DataTable\Renderer\Html;
  15. use Piwik\DataTable\Row;
  16. use Piwik\DataTable\Row\DataTableSummaryRow;
  17. use Piwik\DataTable\Simple;
  18. use Piwik\DataTable\TableNotFoundException;
  19. use ReflectionClass;
  20. /**
  21. * @see Common::destroy()
  22. */
  23. require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
  24. /**
  25. * The primary data structure used to store analytics data in Piwik.
  26. *
  27. * <a name="class-desc-the-basics"></a>
  28. * ### The Basics
  29. *
  30. * DataTables consist of rows and each row consists of columns. A column value can be
  31. * a numeric, a string or an array.
  32. *
  33. * Every row has an ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}.
  34. *
  35. * DataTables are hierarchical data structures. Each row can also contain an additional
  36. * nested sub-DataTable (commonly referred to as a 'subtable').
  37. *
  38. * Both DataTables and DataTable rows can hold **metadata**. _DataTable metadata_ is information
  39. * regarding all the data, such as the site or period that the data is for. _Row metadata_
  40. * is information regarding that row, such as a browser logo or website URL.
  41. *
  42. * Finally, all DataTables contain a special _summary_ row. This row, if it exists, is
  43. * always at the end of the DataTable.
  44. *
  45. * ### Populating DataTables
  46. *
  47. * Data can be added to DataTables in three different ways. You can either:
  48. *
  49. * 1. create rows one by one and add them through {@link addRow()} then truncate if desired,
  50. * 2. create an array of DataTable\Row instances or an array of arrays and add them using
  51. * {@link addRowsFromArray()} or {@link addRowsFromSimpleArray()}
  52. * then truncate if desired,
  53. * 3. or set the maximum number of allowed rows (with {@link setMaximumAllowedRows()})
  54. * and add rows one by one.
  55. *
  56. * If you want to eventually truncate your data (standard practice for all Piwik plugins),
  57. * the third method is the most memory efficient. It is, unfortunately, not always possible
  58. * to use since it requires that the data be sorted before adding.
  59. *
  60. * ### Manipulating DataTables
  61. *
  62. * There are two ways to manipulate a DataTable. You can either:
  63. *
  64. * 1. manually iterate through each row and manipulate the data,
  65. * 2. or you can use predefined filters.
  66. *
  67. * A filter is a class that has a 'filter' method which will manipulate a DataTable in
  68. * some way. There are several predefined Filters that allow you to do common things,
  69. * such as,
  70. *
  71. * - add a new column to each row,
  72. * - add new metadata to each row,
  73. * - modify an existing column value for each row,
  74. * - sort an entire DataTable,
  75. * - and more.
  76. *
  77. * Using these filters instead of writing your own code will increase code clarity and
  78. * reduce code redundancy. Additionally, filters have the advantage that they can be
  79. * applied to DataTable\Map instances. So you can visit every DataTable in a {@link DataTable\Map}
  80. * without having to write a recursive visiting function.
  81. *
  82. * All predefined filters exist in the **Piwik\DataTable\BaseFilter** namespace.
  83. *
  84. * _Note: For convenience, [anonymous functions](http://www.php.net/manual/en/functions.anonymous.php)
  85. * can be used as DataTable filters._
  86. *
  87. * ### Applying Filters
  88. *
  89. * Filters can be applied now (via {@link filter()}), or they can be applied later (via
  90. * {@link queueFilter()}).
  91. *
  92. * Filters that sort rows or manipulate the number of rows should be applied right away.
  93. * Non-essential, presentation filters should be queued.
  94. *
  95. * ### Learn more
  96. *
  97. * - See **{@link ArchiveProcessor}** to learn how DataTables are persisted.
  98. *
  99. * ### Examples
  100. *
  101. * **Populating a DataTable**
  102. *
  103. * // adding one row at a time
  104. * $dataTable = new DataTable();
  105. * $dataTable->addRow(new Row(array(
  106. * Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1),
  107. * Row::METADATA => array('url' => 'http://thing1.com')
  108. * )));
  109. * $dataTable->addRow(new Row(array(
  110. * Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2),
  111. * Row::METADATA => array('url' => 'http://thing2.com')
  112. * )));
  113. *
  114. * // using an array of rows
  115. * $dataTable = new DataTable();
  116. * $dataTable->addRowsFromArray(array(
  117. * array(
  118. * Row::COLUMNS => array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1),
  119. * Row::METADATA => array('url' => 'http://thing1.com')
  120. * ),
  121. * array(
  122. * Row::COLUMNS => array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2),
  123. * Row::METADATA => array('url' => 'http://thing2.com')
  124. * )
  125. * ));
  126. *
  127. * // using a "simple" array
  128. * $dataTable->addRowsFromSimpleArray(array(
  129. * array('label' => 'thing1', 'nb_visits' => 1, 'nb_actions' => 1),
  130. * array('label' => 'thing2', 'nb_visits' => 2, 'nb_actions' => 2)
  131. * ));
  132. *
  133. * **Getting & setting metadata**
  134. *
  135. * $dataTable = \Piwik\Plugins\Referrers\API::getInstance()->getSearchEngines($idSite = 1, $period = 'day', $date = '2007-07-24');
  136. * $oldPeriod = $dataTable->metadata['period'];
  137. * $dataTable->metadata['period'] = Period\Factory::build('week', Date::factory('2013-10-18'));
  138. *
  139. * **Serializing & unserializing**
  140. *
  141. * $maxRowsInTable = Config::getInstance()->General['datatable_archiving_maximum_rows_standard'];j
  142. *
  143. * $dataTable = // ... build by aggregating visits ...
  144. * $serializedData = $dataTable->getSerialized($maxRowsInTable, $maxRowsInSubtable = $maxRowsInTable,
  145. * $columnToSortBy = Metrics::INDEX_NB_VISITS);
  146. *
  147. * $serializedDataTable = $serializedData[0];
  148. * $serailizedSubTable = $serializedData[$idSubtable];
  149. *
  150. * **Filtering for an API method**
  151. *
  152. * public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false)
  153. * {
  154. * $dataTable = Archive::getDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded);
  155. * $dataTable->filter('Sort', array(Metrics::INDEX_NB_VISITS, 'desc', $naturalSort = false, $expanded));
  156. * $dataTable->queueFilter('ReplaceColumnNames');
  157. * $dataTable->queueFilter('ColumnCallbackAddMetadata', array('label', 'url', __NAMESPACE__ . '\getUrlFromLabelForMyReport'));
  158. * return $dataTable;
  159. * }
  160. *
  161. *
  162. * @api
  163. */
  164. class DataTable implements DataTableInterface, \IteratorAggregate, \ArrayAccess
  165. {
  166. const MAX_DEPTH_DEFAULT = 15;
  167. /** Name for metadata that describes when a report was archived. */
  168. const ARCHIVED_DATE_METADATA_NAME = 'archived_date';
  169. /** Name for metadata that describes which columns are empty and should not be shown. */
  170. const EMPTY_COLUMNS_METADATA_NAME = 'empty_column';
  171. /** Name for metadata that describes the number of rows that existed before the Limit filter was applied. */
  172. const TOTAL_ROWS_BEFORE_LIMIT_METADATA_NAME = 'total_rows_before_limit';
  173. /**
  174. * Name for metadata that describes how individual columns should be aggregated when {@link addDataTable()}
  175. * or {@link Piwik\DataTable\Row::sumRow()} is called.
  176. *
  177. * This metadata value must be an array that maps column names with valid operations. Valid aggregation operations are:
  178. *
  179. * - `'skip'`: do nothing
  180. * - `'max'`: does `max($column1, $column2)`
  181. * - `'min'`: does `min($column1, $column2)`
  182. * - `'sum'`: does `$column1 + $column2`
  183. *
  184. * See {@link addDataTable()} and {@link DataTable\Row::sumRow()} for more information.
  185. */
  186. const COLUMN_AGGREGATION_OPS_METADATA_NAME = 'column_aggregation_ops';
  187. /** The ID of the Summary Row. */
  188. const ID_SUMMARY_ROW = -1;
  189. /** The original label of the Summary Row. */
  190. const LABEL_SUMMARY_ROW = -1;
  191. /**
  192. * Maximum nesting level.
  193. */
  194. private static $maximumDepthLevelAllowed = self::MAX_DEPTH_DEFAULT;
  195. /**
  196. * Array of Row
  197. *
  198. * @var Row[]
  199. */
  200. protected $rows = array();
  201. /**
  202. * Id assigned to the DataTable, used to lookup the table using the DataTable_Manager
  203. *
  204. * @var int
  205. */
  206. protected $currentId;
  207. /**
  208. * Current depth level of this data table
  209. * 0 is the parent data table
  210. *
  211. * @var int
  212. */
  213. protected $depthLevel = 0;
  214. /**
  215. * This flag is set to false once we modify the table in a way that outdates the index
  216. *
  217. * @var bool
  218. */
  219. protected $indexNotUpToDate = true;
  220. /**
  221. * This flag sets the index to be rebuild whenever a new row is added,
  222. * as opposed to re-building the full index when getRowFromLabel is called.
  223. * This is to optimize and not rebuild the full Index in the case where we
  224. * add row, getRowFromLabel, addRow, getRowFromLabel thousands of times.
  225. *
  226. * @var bool
  227. */
  228. protected $rebuildIndexContinuously = false;
  229. /**
  230. * Column name of last time the table was sorted
  231. *
  232. * @var string
  233. */
  234. protected $tableSortedBy = false;
  235. /**
  236. * List of BaseFilter queued to this table
  237. *
  238. * @var array
  239. */
  240. protected $queuedFilters = array();
  241. /**
  242. * We keep track of the number of rows before applying the LIMIT filter that deletes some rows
  243. *
  244. * @var int
  245. */
  246. protected $rowsCountBeforeLimitFilter = 0;
  247. /**
  248. * Defaults to false for performance reasons (most of the time we don't need recursive sorting so we save a looping over the dataTable)
  249. *
  250. * @var bool
  251. */
  252. protected $enableRecursiveSort = false;
  253. /**
  254. * When the table and all subtables are loaded, this flag will be set to true to ensure filters are applied to all subtables
  255. *
  256. * @var bool
  257. */
  258. protected $enableRecursiveFilters = false;
  259. /**
  260. * @var array
  261. */
  262. protected $rowsIndexByLabel = array();
  263. /**
  264. * @var \Piwik\DataTable\Row
  265. */
  266. protected $summaryRow = null;
  267. /**
  268. * Table metadata. Read [this](#class-desc-the-basics) to learn more.
  269. *
  270. * Any data that describes the data held in the table's rows should go here.
  271. *
  272. * @var array
  273. */
  274. private $metadata = array();
  275. /**
  276. * Maximum number of rows allowed in this datatable (including the summary row).
  277. * If adding more rows is attempted, the extra rows get summed to the summary row.
  278. *
  279. * @var int
  280. */
  281. protected $maximumAllowedRows = 0;
  282. /**
  283. * Constructor. Creates an empty DataTable.
  284. */
  285. public function __construct()
  286. {
  287. // registers this instance to the manager
  288. $this->currentId = Manager::getInstance()->addTable($this);
  289. }
  290. /**
  291. * Destructor. Makes sure DataTable memory will be cleaned up.
  292. */
  293. public function __destruct()
  294. {
  295. static $depth = 0;
  296. // destruct can be called several times
  297. if ($depth < self::$maximumDepthLevelAllowed
  298. && isset($this->rows)
  299. ) {
  300. $depth++;
  301. foreach ($this->getRows() as $row) {
  302. Common::destroy($row);
  303. }
  304. unset($this->rows);
  305. Manager::getInstance()->setTableDeleted($this->getId());
  306. $depth--;
  307. }
  308. }
  309. /**
  310. * Sorts the DataTable rows using the supplied callback function.
  311. *
  312. * @param string $functionCallback A comparison callback compatible with {@link usort}.
  313. * @param string $columnSortedBy The column name `$functionCallback` sorts by. This is stored
  314. * so we can determine how the DataTable was sorted in the future.
  315. */
  316. public function sort($functionCallback, $columnSortedBy)
  317. {
  318. $this->indexNotUpToDate = true;
  319. $this->tableSortedBy = $columnSortedBy;
  320. usort($this->rows, $functionCallback);
  321. if ($this->enableRecursiveSort === true) {
  322. foreach ($this->getRows() as $row) {
  323. if (($idSubtable = $row->getIdSubDataTable()) !== null) {
  324. $table = Manager::getInstance()->getTable($idSubtable);
  325. $table->enableRecursiveSort();
  326. $table->sort($functionCallback, $columnSortedBy);
  327. }
  328. }
  329. }
  330. }
  331. /**
  332. * Returns the name of the column this table was sorted by (if any).
  333. *
  334. * See {@link sort()}.
  335. *
  336. * @return false|string The sorted column name or false if none.
  337. */
  338. public function getSortedByColumnName()
  339. {
  340. return $this->tableSortedBy;
  341. }
  342. /**
  343. * Enables recursive sorting. If this method is called {@link sort()} will also sort all
  344. * subtables.
  345. */
  346. public function enableRecursiveSort()
  347. {
  348. $this->enableRecursiveSort = true;
  349. }
  350. /**
  351. * Enables recursive filtering. If this method is called then the {@link filter()} method
  352. * will apply filters to every subtable in addition to this instance.
  353. */
  354. public function enableRecursiveFilters()
  355. {
  356. $this->enableRecursiveFilters = true;
  357. }
  358. /**
  359. * Applies a filter to this datatable.
  360. *
  361. * If {@link enableRecursiveFilters()} was called, the filter will be applied
  362. * to all subtables as well.
  363. *
  364. * @param string|Closure $className Class name, eg. `"Sort"` or "Piwik\DataTable\Filters\Sort"`. If no
  365. * namespace is supplied, `Piwik\DataTable\BaseFilter` is assumed. This parameter
  366. * can also be a closure that takes a DataTable as its first parameter.
  367. * @param array $parameters Array of extra parameters to pass to the filter.
  368. */
  369. public function filter($className, $parameters = array())
  370. {
  371. if ($className instanceof \Closure
  372. || is_array($className)
  373. ) {
  374. array_unshift($parameters, $this);
  375. call_user_func_array($className, $parameters);
  376. return;
  377. }
  378. if (!class_exists($className, true)) {
  379. $className = 'Piwik\DataTable\Filter\\' . $className;
  380. }
  381. $reflectionObj = new ReflectionClass($className);
  382. // the first parameter of a filter is the DataTable
  383. // we add the current datatable as the parameter
  384. $parameters = array_merge(array($this), $parameters);
  385. $filter = $reflectionObj->newInstanceArgs($parameters);
  386. $filter->enableRecursive($this->enableRecursiveFilters);
  387. $filter->filter($this);
  388. }
  389. /**
  390. * Adds a filter and a list of parameters to the list of queued filters. These filters will be
  391. * executed when {@link applyQueuedFilters()} is called.
  392. *
  393. * Filters that prettify the column values or don't need the full set of rows should be queued. This
  394. * way they will be run after the table is truncated which will result in better performance.
  395. *
  396. * @param string|Closure $className The class name of the filter, eg. `'Limit'`.
  397. * @param array $parameters The parameters to give to the filter, eg. `array($offset, $limit)` for the Limit filter.
  398. */
  399. public function queueFilter($className, $parameters = array())
  400. {
  401. if (!is_array($parameters)) {
  402. $parameters = array($parameters);
  403. }
  404. $this->queuedFilters[] = array('className' => $className, 'parameters' => $parameters);
  405. }
  406. /**
  407. * Applies all filters that were previously queued to the table. See {@link queueFilter()}
  408. * for more information.
  409. */
  410. public function applyQueuedFilters()
  411. {
  412. foreach ($this->queuedFilters as $filter) {
  413. $this->filter($filter['className'], $filter['parameters']);
  414. }
  415. $this->clearQueuedFilters();
  416. }
  417. /**
  418. * Sums a DataTable to this one.
  419. *
  420. * This method will sum rows that have the same label. If a row is found in `$tableToSum` whose
  421. * label is not found in `$this`, the row will be added to `$this`.
  422. *
  423. * If the subtables for this table are loaded, they will be summed as well.
  424. *
  425. * Rows are summed together by summing individual columns. By default columns are summed by
  426. * adding one column value to another. Some columns cannot be aggregated this way. In these
  427. * cases, the {@link COLUMN_AGGREGATION_OPS_METADATA_NAME}
  428. * metadata can be used to specify a different type of operation.
  429. *
  430. * @param \Piwik\DataTable $tableToSum
  431. */
  432. public function addDataTable(DataTable $tableToSum, $doAggregateSubTables = true)
  433. {
  434. if($tableToSum instanceof Simple) {
  435. if($tableToSum->getRowsCount() > 1) {
  436. throw new Exception("Did not expect a Simple table with more than one row in addDataTable()");
  437. }
  438. $row = $tableToSum->getFirstRow();
  439. $this->aggregateRowFromSimpleTable($row);
  440. } else {
  441. foreach ($tableToSum->getRows() as $row) {
  442. $this->aggregateRowWithLabel($row, $doAggregateSubTables);
  443. }
  444. }
  445. }
  446. /**
  447. * Returns the Row whose `'label'` column is equal to `$label`.
  448. *
  449. * This method executes in constant time except for the first call which caches row
  450. * label => row ID mappings.
  451. *
  452. * @param string $label `'label'` column value to look for.
  453. * @return Row|false The row if found, `false` if otherwise.
  454. */
  455. public function getRowFromLabel($label)
  456. {
  457. $rowId = $this->getRowIdFromLabel($label);
  458. if ($rowId instanceof Row) {
  459. return $rowId;
  460. }
  461. if (is_int($rowId) && isset($this->rows[$rowId])) {
  462. return $this->rows[$rowId];
  463. }
  464. if ($rowId == self::ID_SUMMARY_ROW
  465. && !empty($this->summaryRow)
  466. ) {
  467. return $this->summaryRow;
  468. }
  469. return false;
  470. }
  471. /**
  472. * Returns the row id for the row whose `'label'` column is equal to `$label`.
  473. *
  474. * This method executes in constant time except for the first call which caches row
  475. * label => row ID mappings.
  476. *
  477. * @param string $label `'label'` column value to look for.
  478. * @return int The row ID.
  479. */
  480. public function getRowIdFromLabel($label)
  481. {
  482. $this->rebuildIndexContinuously = true;
  483. if ($this->indexNotUpToDate) {
  484. $this->rebuildIndex();
  485. }
  486. if ($label === self::LABEL_SUMMARY_ROW
  487. && !is_null($this->summaryRow)
  488. ) {
  489. return self::ID_SUMMARY_ROW;
  490. }
  491. $label = (string)$label;
  492. if (!isset($this->rowsIndexByLabel[$label])) {
  493. return false;
  494. }
  495. return $this->rowsIndexByLabel[$label];
  496. }
  497. /**
  498. * Returns an empty DataTable with the same metadata and queued filters as `$this` one.
  499. *
  500. * @param bool $keepFilters Whether to pass the queued filter list to the new DataTable or not.
  501. * @return DataTable
  502. */
  503. public function getEmptyClone($keepFilters = true)
  504. {
  505. $clone = new DataTable;
  506. if ($keepFilters) {
  507. $clone->queuedFilters = $this->queuedFilters;
  508. }
  509. $clone->metadata = $this->metadata;
  510. return $clone;
  511. }
  512. /**
  513. * Rebuilds the index used to lookup a row by label
  514. */
  515. private function rebuildIndex()
  516. {
  517. foreach ($this->getRows() as $id => $row) {
  518. $label = $row->getColumn('label');
  519. if ($label !== false) {
  520. $this->rowsIndexByLabel[$label] = $id;
  521. }
  522. }
  523. $this->indexNotUpToDate = false;
  524. }
  525. /**
  526. * Returns a row by ID. The ID is either the index of the row or {@link ID_SUMMARY_ROW}.
  527. *
  528. * @param int $id The row ID.
  529. * @return Row|false The Row or false if not found.
  530. */
  531. public function getRowFromId($id)
  532. {
  533. if (!isset($this->rows[$id])) {
  534. if ($id == self::ID_SUMMARY_ROW
  535. && !is_null($this->summaryRow)
  536. ) {
  537. return $this->summaryRow;
  538. }
  539. return false;
  540. }
  541. return $this->rows[$id];
  542. }
  543. /**
  544. * Returns the row that has a subtable with ID matching `$idSubtable`.
  545. *
  546. * @param int $idSubTable The subtable ID.
  547. * @return Row|false The row or false if not found
  548. */
  549. public function getRowFromIdSubDataTable($idSubTable)
  550. {
  551. $idSubTable = (int)$idSubTable;
  552. foreach ($this->rows as $row) {
  553. if ($row->getIdSubDataTable() === $idSubTable) {
  554. return $row;
  555. }
  556. }
  557. return false;
  558. }
  559. /**
  560. * Adds a row to this table.
  561. *
  562. * If {@link setMaximumAllowedRows()} was called and the current row count is
  563. * at the maximum, the new row will be summed to the summary row. If there is no summary row,
  564. * this row is set as the summary row.
  565. *
  566. * @param Row $row
  567. * @return Row `$row` or the summary row if we're at the maximum number of rows.
  568. */
  569. public function addRow(Row $row)
  570. {
  571. // if there is a upper limit on the number of allowed rows and the table is full,
  572. // add the new row to the summary row
  573. if ($this->maximumAllowedRows > 0
  574. && $this->getRowsCount() >= $this->maximumAllowedRows - 1
  575. ) {
  576. if ($this->summaryRow === null) // create the summary row if necessary
  577. {
  578. $columns = array('label' => self::LABEL_SUMMARY_ROW) + $row->getColumns();
  579. $this->addSummaryRow(new Row(array(Row::COLUMNS => $columns)));
  580. } else {
  581. $this->summaryRow->sumRow(
  582. $row, $enableCopyMetadata = false, $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME));
  583. }
  584. return $this->summaryRow;
  585. }
  586. $this->rows[] = $row;
  587. if (!$this->indexNotUpToDate
  588. && $this->rebuildIndexContinuously
  589. ) {
  590. $label = $row->getColumn('label');
  591. if ($label !== false) {
  592. $this->rowsIndexByLabel[$label] = count($this->rows) - 1;
  593. }
  594. }
  595. return $row;
  596. }
  597. /**
  598. * Sets the summary row.
  599. *
  600. * _Note: A DataTable can have only one summary row._
  601. *
  602. * @param Row $row
  603. * @return Row Returns `$row`.
  604. */
  605. public function addSummaryRow(Row $row)
  606. {
  607. $this->summaryRow = $row;
  608. // add summary row to index
  609. if (!$this->indexNotUpToDate
  610. && $this->rebuildIndexContinuously
  611. ) {
  612. $label = $row->getColumn('label');
  613. if ($label !== false) {
  614. $this->rowsIndexByLabel[$label] = self::ID_SUMMARY_ROW;
  615. }
  616. }
  617. return $row;
  618. }
  619. /**
  620. * Returns the DataTable ID.
  621. *
  622. * @return int
  623. */
  624. public function getId()
  625. {
  626. return $this->currentId;
  627. }
  628. /**
  629. * Adds a new row from an array.
  630. *
  631. * You can add row metadata with this method.
  632. *
  633. * @param array $row eg. `array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'),
  634. * Row::METADATA => array('mymetadata' => 'myvalue'))`
  635. */
  636. public function addRowFromArray($row)
  637. {
  638. $this->addRowsFromArray(array($row));
  639. }
  640. /**
  641. * Adds a new row a from an array of column values.
  642. *
  643. * Row metadata cannot be added with this method.
  644. *
  645. * @param array $row eg. `array('name' => 'google analytics', 'license' => 'commercial')`
  646. */
  647. public function addRowFromSimpleArray($row)
  648. {
  649. $this->addRowsFromSimpleArray(array($row));
  650. }
  651. /**
  652. * Returns the array of Rows.
  653. *
  654. * @return Row[]
  655. */
  656. public function getRows()
  657. {
  658. if (is_null($this->summaryRow)) {
  659. return $this->rows;
  660. } else {
  661. return $this->rows + array(self::ID_SUMMARY_ROW => $this->summaryRow);
  662. }
  663. }
  664. /**
  665. * Returns an array containing all column values for the requested column.
  666. *
  667. * @param string $name The column name.
  668. * @return array The array of column values.
  669. */
  670. public function getColumn($name)
  671. {
  672. $columnValues = array();
  673. foreach ($this->getRows() as $row) {
  674. $columnValues[] = $row->getColumn($name);
  675. }
  676. return $columnValues;
  677. }
  678. /**
  679. * Returns an array containing all column values of columns whose name starts with `$name`.
  680. *
  681. * @param $namePrefix The column name prefix.
  682. * @return array The array of column values.
  683. */
  684. public function getColumnsStartingWith($namePrefix)
  685. {
  686. $columnValues = array();
  687. foreach ($this->getRows() as $row) {
  688. $columns = $row->getColumns();
  689. foreach ($columns as $column => $value) {
  690. if (strpos($column, $namePrefix) === 0) {
  691. $columnValues[] = $row->getColumn($column);
  692. }
  693. }
  694. }
  695. return $columnValues;
  696. }
  697. /**
  698. * Returns the names of every column this DataTable contains. This method will return the
  699. * columns of the first row with data and will assume they occur in every other row as well.
  700. *
  701. *_ Note: If column names still use their in-database INDEX values (@see Metrics), they
  702. * will be converted to their string name in the array result._
  703. *
  704. * @return array Array of string column names.
  705. */
  706. public function getColumns()
  707. {
  708. $result = array();
  709. foreach ($this->getRows() as $row) {
  710. $columns = $row->getColumns();
  711. if (!empty($columns)) {
  712. $result = array_keys($columns);
  713. break;
  714. }
  715. }
  716. // make sure column names are not DB index values
  717. foreach ($result as &$column) {
  718. if (isset(Metrics::$mappingFromIdToName[$column])) {
  719. $column = Metrics::$mappingFromIdToName[$column];
  720. }
  721. }
  722. return $result;
  723. }
  724. /**
  725. * Returns an array containing the requested metadata value of each row.
  726. *
  727. * @param string $name The metadata column to return.
  728. * @return array
  729. */
  730. public function getRowsMetadata($name)
  731. {
  732. $metadataValues = array();
  733. foreach ($this->getRows() as $row) {
  734. $metadataValues[] = $row->getMetadata($name);
  735. }
  736. return $metadataValues;
  737. }
  738. /**
  739. * Returns the number of rows in the table including the summary row.
  740. *
  741. * @return int
  742. */
  743. public function getRowsCount()
  744. {
  745. if (is_null($this->summaryRow)) {
  746. return count($this->rows);
  747. } else {
  748. return count($this->rows) + 1;
  749. }
  750. }
  751. /**
  752. * Returns the first row of the DataTable.
  753. *
  754. * @return Row|false The first row or `false` if it cannot be found.
  755. */
  756. public function getFirstRow()
  757. {
  758. if (count($this->rows) == 0) {
  759. if (!is_null($this->summaryRow)) {
  760. return $this->summaryRow;
  761. }
  762. return false;
  763. }
  764. return reset($this->rows);
  765. }
  766. /**
  767. * Returns the last row of the DataTable. If there is a summary row, it
  768. * will always be considered the last row.
  769. *
  770. * @return Row|false The last row or `false` if it cannot be found.
  771. */
  772. public function getLastRow()
  773. {
  774. if (!is_null($this->summaryRow)) {
  775. return $this->summaryRow;
  776. }
  777. if (count($this->rows) == 0) {
  778. return false;
  779. }
  780. return end($this->rows);
  781. }
  782. /**
  783. * Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable
  784. * summed with the row count of each descendant subtable.
  785. *
  786. * @return int
  787. */
  788. public function getRowsCountRecursive()
  789. {
  790. $totalCount = 0;
  791. foreach ($this->rows as $row) {
  792. if (($idSubTable = $row->getIdSubDataTable()) !== null) {
  793. $subTable = Manager::getInstance()->getTable($idSubTable);
  794. $count = $subTable->getRowsCountRecursive();
  795. $totalCount += $count;
  796. }
  797. }
  798. $totalCount += $this->getRowsCount();
  799. return $totalCount;
  800. }
  801. /**
  802. * Delete a column by name in every row. This change is NOT applied recursively to all
  803. * subtables.
  804. *
  805. * @param string $name Column name to delete.
  806. */
  807. public function deleteColumn($name)
  808. {
  809. $this->deleteColumns(array($name));
  810. }
  811. public function __sleep()
  812. {
  813. return array('rows', 'summaryRow');
  814. }
  815. /**
  816. * Rename a column in every row. This change is applied recursively to all subtables.
  817. *
  818. * @param string $oldName Old column name.
  819. * @param string $newName New column name.
  820. */
  821. public function renameColumn($oldName, $newName, $doRenameColumnsOfSubTables = true)
  822. {
  823. foreach ($this->getRows() as $row) {
  824. $row->renameColumn($oldName, $newName);
  825. if($doRenameColumnsOfSubTables) {
  826. if (($idSubDataTable = $row->getIdSubDataTable()) !== null) {
  827. Manager::getInstance()->getTable($idSubDataTable)->renameColumn($oldName, $newName);
  828. }
  829. }
  830. }
  831. if (!is_null($this->summaryRow)) {
  832. $this->summaryRow->renameColumn($oldName, $newName);
  833. }
  834. }
  835. /**
  836. * Deletes several columns by name in every row.
  837. *
  838. * @param array $names List of column names to delete.
  839. * @param bool $deleteRecursiveInSubtables Whether to apply this change to all subtables or not.
  840. */
  841. public function deleteColumns($names, $deleteRecursiveInSubtables = false)
  842. {
  843. foreach ($this->getRows() as $row) {
  844. foreach ($names as $name) {
  845. $row->deleteColumn($name);
  846. }
  847. if (($idSubDataTable = $row->getIdSubDataTable()) !== null) {
  848. Manager::getInstance()->getTable($idSubDataTable)->deleteColumns($names, $deleteRecursiveInSubtables);
  849. }
  850. }
  851. if (!is_null($this->summaryRow)) {
  852. foreach ($names as $name) {
  853. $this->summaryRow->deleteColumn($name);
  854. }
  855. }
  856. }
  857. /**
  858. * Deletes a row by ID.
  859. *
  860. * @param int $id The row ID.
  861. * @throws Exception If the row `$id` cannot be found.
  862. */
  863. public function deleteRow($id)
  864. {
  865. if ($id === self::ID_SUMMARY_ROW) {
  866. $this->summaryRow = null;
  867. return;
  868. }
  869. if (!isset($this->rows[$id])) {
  870. throw new Exception("Trying to delete unknown row with idkey = $id");
  871. }
  872. unset($this->rows[$id]);
  873. }
  874. /**
  875. * Deletes rows from `$offset` to `$offset + $limit`.
  876. *
  877. * @param int $offset The offset to start deleting rows from.
  878. * @param int|null $limit The number of rows to delete. If `null` all rows after the offset
  879. * will be removed.
  880. * @return int The number of rows deleted.
  881. */
  882. public function deleteRowsOffset($offset, $limit = null)
  883. {
  884. if ($limit === 0) {
  885. return 0;
  886. }
  887. $count = $this->getRowsCount();
  888. if ($offset >= $count) {
  889. return 0;
  890. }
  891. // if we delete until the end, we delete the summary row as well
  892. if (is_null($limit)
  893. || $limit >= $count
  894. ) {
  895. $this->summaryRow = null;
  896. }
  897. if (is_null($limit)) {
  898. $spliced = array_splice($this->rows, $offset);
  899. } else {
  900. $spliced = array_splice($this->rows, $offset, $limit);
  901. }
  902. $countDeleted = count($spliced);
  903. return $countDeleted;
  904. }
  905. /**
  906. * Deletes a set of rows by ID.
  907. *
  908. * @param array $rowIds The list of row IDs to delete.
  909. * @throws Exception If a row ID cannot be found.
  910. */
  911. public function deleteRows(array $rowIds)
  912. {
  913. foreach ($rowIds as $key) {
  914. $this->deleteRow($key);
  915. }
  916. }
  917. /**
  918. * Returns a string representation of this DataTable for convenient viewing.
  919. *
  920. * _Note: This uses the **html** DataTable renderer._
  921. *
  922. * @return string
  923. */
  924. public function __toString()
  925. {
  926. $renderer = new Html();
  927. $renderer->setTable($this);
  928. return (string)$renderer;
  929. }
  930. /**
  931. * Returns true if both DataTable instances are exactly the same.
  932. *
  933. * DataTables are equal if they have the same number of rows, if
  934. * each row has a label that exists in the other table, and if each row
  935. * is equal to the row in the other table with the same label. The order
  936. * of rows is not important.
  937. *
  938. * @param \Piwik\DataTable $table1
  939. * @param \Piwik\DataTable $table2
  940. * @return bool
  941. */
  942. public static function isEqual(DataTable $table1, DataTable $table2)
  943. {
  944. $rows1 = $table1->getRows();
  945. $table1->rebuildIndex();
  946. $table2->rebuildIndex();
  947. if ($table1->getRowsCount() != $table2->getRowsCount()) {
  948. return false;
  949. }
  950. foreach ($rows1 as $row1) {
  951. $row2 = $table2->getRowFromLabel($row1->getColumn('label'));
  952. if ($row2 === false
  953. || !Row::isEqual($row1, $row2)
  954. ) {
  955. return false;
  956. }
  957. }
  958. return true;
  959. }
  960. /**
  961. * Serializes an entire DataTable hierarchy and returns the array of serialized DataTables.
  962. *
  963. * The first element in the returned array will be the serialized representation of this DataTable.
  964. * Every subsequent element will be a serialized subtable.
  965. *
  966. * This DataTable and subtables can optionally be truncated before being serialized. In most
  967. * cases where DataTables can become quite large, they should be truncated before being persisted
  968. * in an archive.
  969. *
  970. * The result of this method is intended for use with the {@link ArchiveProcessor::insertBlobRecord()} method.
  971. *
  972. * @throws Exception If infinite recursion detected. This will occur if a table's subtable is one of its parent tables.
  973. * @param int $maximumRowsInDataTable If not null, defines the maximum number of rows allowed in the serialized DataTable.
  974. * @param int $maximumRowsInSubDataTable If not null, defines the maximum number of rows allowed in serialized subtables.
  975. * @param string $columnToSortByBeforeTruncation The column to sort by before truncating, eg, `Metrics::INDEX_NB_VISITS`.
  976. * @return array The array of serialized DataTables:
  977. *
  978. * array(
  979. * // this DataTable (the root)
  980. * 0 => 'eghuighahgaueytae78yaet7yaetae',
  981. *
  982. * // a subtable
  983. * 1 => 'gaegae gh gwrh guiwh uigwhuige',
  984. *
  985. * // another subtable
  986. * 2 => 'gqegJHUIGHEQjkgneqjgnqeugUGEQHGUHQE',
  987. *
  988. * // etc.
  989. * );
  990. */
  991. public function getSerialized($maximumRowsInDataTable = null,
  992. $maximumRowsInSubDataTable = null,
  993. $columnToSortByBeforeTruncation = null)
  994. {
  995. static $depth = 0;
  996. if ($depth > self::$maximumDepthLevelAllowed) {
  997. $depth = 0;
  998. 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?");
  999. }
  1000. if (!is_null($maximumRowsInDataTable)) {
  1001. $this->filter('Truncate',
  1002. array($maximumRowsInDataTable - 1,
  1003. DataTable::LABEL_SUMMARY_ROW,
  1004. $columnToSortByBeforeTruncation,
  1005. $filterRecursive = false)
  1006. );
  1007. }
  1008. // For each row, get the serialized row
  1009. // If it is associated to a sub table, get the serialized table recursively ;
  1010. // but returns all serialized tables and subtable in an array of 1 dimension
  1011. $aSerializedDataTable = array();
  1012. foreach ($this->rows as $row) {
  1013. if (($idSubTable = $row->getIdSubDataTable()) !== null) {
  1014. $subTable = null;
  1015. try {
  1016. $subTable = Manager::getInstance()->getTable($idSubTable);
  1017. } catch(TableNotFoundException $e) {
  1018. // This occurs is an unknown & random data issue. Catch Exception and remove subtable from the row.
  1019. $row->removeSubtable();
  1020. // Go to next row
  1021. continue;
  1022. }
  1023. $depth++;
  1024. $aSerializedDataTable = $aSerializedDataTable + $subTable->getSerialized($maximumRowsInSubDataTable, $maximumRowsInSubDataTable, $columnToSortByBeforeTruncation);
  1025. $depth--;
  1026. }
  1027. }
  1028. // we load the current Id of the DataTable
  1029. $forcedId = $this->getId();
  1030. // if the datatable is the parent we force the Id at 0 (this is part of the specification)
  1031. if ($depth == 0) {
  1032. $forcedId = 0;
  1033. }
  1034. // we then serialize the rows and store them in the serialized dataTable
  1035. $addToRows = array(self::ID_SUMMARY_ROW => $this->summaryRow);
  1036. $aSerializedDataTable[$forcedId] = serialize($this->rows + $addToRows);
  1037. foreach ($this->rows as &$row) {
  1038. $row->cleanPostSerialize();
  1039. }
  1040. return $aSerializedDataTable;
  1041. }
  1042. /**
  1043. * Adds a set of rows from a serialized DataTable string.
  1044. *
  1045. * See {@link serialize()}.
  1046. *
  1047. * _Note: This function will successfully load DataTables serialized by Piwik 1.X._
  1048. *
  1049. * @param string $stringSerialized A string with the format of a string in the array returned by
  1050. * {@link serialize()}.
  1051. * @throws Exception if `$stringSerialized` is invalid.
  1052. */
  1053. public function addRowsFromSerializedArray($stringSerialized)
  1054. {
  1055. require_once PIWIK_INCLUDE_PATH . "/core/DataTable/Bridges.php";
  1056. $serialized = unserialize($stringSerialized);
  1057. if ($serialized === false) {
  1058. throw new Exception("The unserialization has failed!");
  1059. }
  1060. $this->addRowsFromArray($serialized);
  1061. }
  1062. /**
  1063. * Adds multiple rows from an array.
  1064. *
  1065. * You can add row metadata with this method.
  1066. *
  1067. * @param array $array Array with the following structure
  1068. *
  1069. * array(
  1070. * // row1
  1071. * array(
  1072. * Row::COLUMNS => array( col1_name => value1, col2_name => value2, ...),
  1073. * Row::METADATA => array( metadata1_name => value1, ...), // see Row
  1074. * ),
  1075. * // row2
  1076. * array( ... ),
  1077. * )
  1078. */
  1079. public function addRowsFromArray($array)
  1080. {
  1081. foreach ($array as $id => $row) {
  1082. if (is_array($row)) {
  1083. $row = new Row($row);
  1084. }
  1085. if ($id == self::ID_SUMMARY_ROW) {
  1086. $this->summaryRow = $row;
  1087. } else {
  1088. $this->addRow($row);
  1089. }
  1090. }
  1091. }
  1092. /**
  1093. * Adds multiple rows from an array containing arrays of column values.
  1094. *
  1095. * Row metadata cannot be added with this method.
  1096. *
  1097. * @param array $array Array with the following structure:
  1098. *
  1099. * array(
  1100. * array( col1_name => valueA, col2_name => valueC, ...),
  1101. * array( col1_name => valueB, col2_name => valueD, ...),
  1102. * )
  1103. * @throws Exception if `$array` is in an incorrect format.
  1104. */
  1105. public function addRowsFromSimpleArray($array)
  1106. {
  1107. if (count($array) === 0) {
  1108. return;
  1109. }
  1110. // we define an exception we may throw if at one point we notice that we cannot handle the data structure
  1111. $e = new Exception(" Data structure returned is not convertible in the requested format." .
  1112. " Try to call this method with the parameters '&format=original&serialize=1'" .
  1113. "; you will get the original php data structure serialized." .
  1114. " The data structure looks like this: \n \$data = " . var_export($array, true) . "; ");
  1115. // first pass to see if the array has the structure
  1116. // array(col1_name => val1, col2_name => val2, etc.)
  1117. // with val* that are never arrays (only strings/numbers/bool/etc.)
  1118. // if we detect such a "simple" data structure we convert it to a row with the correct columns' names
  1119. $thisIsNotThatSimple = false;
  1120. foreach ($array as $columnValue) {
  1121. if (is_array($columnValue) || is_object($columnValue)) {
  1122. $thisIsNotThatSimple = true;
  1123. break;
  1124. }
  1125. }
  1126. if ($thisIsNotThatSimple === false) {
  1127. // case when the array is indexed by the default numeric index
  1128. if (array_keys($array) == array_keys(array_fill(0, count($array), true))) {
  1129. foreach ($array as $row) {
  1130. $this->addRow(new Row(array(Row::COLUMNS => array($row))));
  1131. }
  1132. } else {
  1133. $this->addRow(new Row(array(Row::COLUMNS => $array)));
  1134. }
  1135. // we have converted our simple array to one single row
  1136. // => we exit the method as the job is now finished
  1137. return;
  1138. }
  1139. foreach ($array as $key => $row) {
  1140. // stuff that looks like a line
  1141. if (is_array($row)) {
  1142. /**
  1143. * We make sure we can convert this PHP array without losing information.
  1144. * We are able to convert only simple php array (no strings keys, no sub arrays, etc.)
  1145. *
  1146. */
  1147. // if the key is a string it means that some information was contained in this key.
  1148. // it cannot be lost during the conversion. Because we are not able to handle properly
  1149. // this key, we throw an explicit exception.
  1150. if (is_string($key)) {
  1151. throw $e;
  1152. }
  1153. // if any of the sub elements of row is an array we cannot handle this data structure...
  1154. foreach ($row as $subRow) {
  1155. if (is_array($subRow)) {
  1156. throw $e;
  1157. }
  1158. }
  1159. $row = new Row(array(Row::COLUMNS => $row));
  1160. } // other (string, numbers...) => we build a line from this value
  1161. else {
  1162. $row = new Row(array(Row::COLUMNS => array($key => $row)));
  1163. }
  1164. $this->addRow($row);
  1165. }
  1166. }
  1167. /**
  1168. * Rewrites the input `$array`
  1169. *
  1170. * array (
  1171. * LABEL => array(col1 => X, col2 => Y),
  1172. * LABEL2 => array(col1 => X, col2 => Y),
  1173. * )
  1174. *
  1175. * to a DataTable with rows that look like:
  1176. *
  1177. * array (
  1178. * array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)),
  1179. * array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)),
  1180. * )
  1181. *
  1182. * Will also convert arrays like:
  1183. *
  1184. * array (
  1185. * LABEL => X,
  1186. * LABEL2 => Y,
  1187. * )
  1188. *
  1189. * to:
  1190. *
  1191. * array (
  1192. * array( Row::COLUMNS => array('label' => LABEL, 'value' => X)),
  1193. * array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)),
  1194. * )
  1195. *
  1196. * @param array $array Indexed array, two formats supported, see above.
  1197. * @param array|null $subtablePerLabel An array mapping label values with DataTable instances to associate as a subtable.
  1198. * @return \Piwik\DataTable
  1199. */
  1200. public static function makeFromIndexedArray($array, $subtablePerLabel = null)
  1201. {
  1202. $table = new DataTable();
  1203. foreach ($array as $label => $row) {
  1204. $cleanRow = array();
  1205. // Support the case of an $array of single values
  1206. if (!is_array($row)) {
  1207. $row = array('value' => $row);
  1208. }
  1209. // Put the 'label' column first
  1210. $cleanRow[Row::COLUMNS] = array('label' => $label) + $row;
  1211. // Assign subtable if specified
  1212. if (isset($subtablePerLabel[$label])) {
  1213. $cleanRow[Row::DATATABLE_ASSOCIATED] = $subtablePerLabel[$label];
  1214. }
  1215. $table->addRow(new Row($cleanRow));
  1216. }
  1217. return $table;
  1218. }
  1219. /**
  1220. * Sets the maximum depth level to at least a certain value. If the current value is
  1221. * greater than `$atLeastLevel`, the maximum nesting level is not changed.
  1222. *
  1223. * The maximum depth level determines the maximum number of subtable levels in the
  1224. * DataTable tree. For example, if it is set to `2`, this DataTable is allowed to
  1225. * have subtables, but the subtables are not.
  1226. *
  1227. * @param int $atLeastLevel
  1228. */
  1229. public static function setMaximumDepthLevelAllowedAtLeast($atLeastLevel)
  1230. {
  1231. self::$maximumDepthLevelAllowed = max($atLeastLevel, self::$maximumDepthLevelAllowed);
  1232. if (self::$maximumDepthLevelAllowed < 1) {
  1233. self::$maximumDepthLevelAllowed = 1;
  1234. }
  1235. }
  1236. /**
  1237. * Returns metadata by name.
  1238. *
  1239. * @param string $name The metadata name.
  1240. * @return mixed|false The metadata value or `false` if it cannot be found.
  1241. */
  1242. public function getMetadata($name)
  1243. {
  1244. if (!isset($this->metadata[$name])) {
  1245. return false;
  1246. }
  1247. return $this->metadata[$name];
  1248. }
  1249. /**
  1250. * Sets a metadata value by name.
  1251. *
  1252. * @param string $name The metadata name.
  1253. * @param mixed $value
  1254. */
  1255. public function setMetadata($name, $value)
  1256. {
  1257. $this->metadata[$name] = $value;
  1258. }
  1259. /**
  1260. * Returns all table metadata.
  1261. *
  1262. * @return array
  1263. */
  1264. public function getAllTableMetadata()
  1265. {
  1266. return $this->metadata;
  1267. }
  1268. /**
  1269. * Sets several metadata values by name.
  1270. *
  1271. * @param array $values Array mapping metadata names with metadata values.
  1272. */
  1273. public function setMetadataValues($values)
  1274. {
  1275. foreach ($values as $name => $value) {
  1276. $this->metadata[$name] = $value;
  1277. }
  1278. }
  1279. /**
  1280. * Sets metadata, erasing existing values.
  1281. *
  1282. * @param array $values Array mapping metadata names with metadata values.
  1283. */
  1284. public function setAllTableMetadata($metadata)
  1285. {
  1286. $this->metadata = $metadata;
  1287. }
  1288. /**
  1289. * Sets the maximum number of rows allowed in this datatable (including the summary
  1290. * row). If adding more then the allowed number of rows is attempted, the extra
  1291. * rows are summed to the summary row.
  1292. *
  1293. * @param int $maximumAllowedRows If `0`, the maximum number of rows is unset.
  1294. */
  1295. public function setMaximumAllowedRows($maximumAllowedRows)
  1296. {
  1297. $this->maximumAllowedRows = $maximumAllowedRows;
  1298. }
  1299. /**
  1300. * Traverses a DataTable tree using an array of labels and returns the row
  1301. * it finds or `false` if it cannot find one. The number of path segments that
  1302. * were successfully walked is also returned.
  1303. *
  1304. * If `$missingRowColumns` is supplied, the specified path is created. When
  1305. * a subtable is encountered w/o the required label, a new row is created
  1306. * with the label, and a new subtable is added to the row.
  1307. *
  1308. * Read [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods](http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods)
  1309. * for more information about tree walking.
  1310. *
  1311. * @param array $path The path to walk. An array of label values. The first element
  1312. * refers to a row in this DataTable, the second in a subtable of
  1313. * the first row, the third a subtable of the second row, etc.
  1314. * @param array|bool $missingRowColumns The default columns to use when creating new rows.
  1315. * If this parameter is supplied, new rows will be
  1316. * created for path labels that cannot be found.
  1317. * @param int $maxSubtableRows The maximum number of allowed rows in new subtables. New
  1318. * subtables are only created if `$missingRowColumns` is provided.
  1319. * @return array First element is the found row or `false`. Second element is
  1320. * the number of path segments walked. If a row is found, this
  1321. * will be == to `count($path)`. Otherwise, it will be the index
  1322. * of the path segment that we could not find.
  1323. */
  1324. public function walkPath($path, $missingRowColumns = false, $maxSubtableRows = 0)
  1325. {
  1326. $pathLength = count($path);
  1327. $table = $this;
  1328. $next = false;
  1329. for ($i = 0; $i < $pathLength; ++$i) {
  1330. $segment = $path[$i];
  1331. $next = $table->getRowFromLabel($segment);
  1332. if ($next === false) {
  1333. // if there is no table to advance to, and we're not adding missing rows, return false
  1334. if ($missingRowColumns === false) {
  1335. return array(false, $i);
  1336. } else // if we're adding missing rows, add a new row
  1337. {
  1338. $row = new DataTableSummaryRow();
  1339. $row->setColumns(array('label' => $segment) + $missingRowColumns);
  1340. $next = $table->addRow($row);
  1341. if ($next !== $row) // if the row wasn't added, the table is full
  1342. {
  1343. // Summary row, has no metadata
  1344. $next->deleteMetadata();
  1345. return array($next, $i);
  1346. }
  1347. }
  1348. }
  1349. $table = $next->getSubtable();
  1350. if ($table === false) {
  1351. // if the row has no table (and thus no child rows), and we're not adding
  1352. // missing rows, return false
  1353. if ($missingRowColumns === false) {
  1354. return array(false, $i);
  1355. } else if ($i != $pathLength - 1) // create subtable if missing, but only if not on the last segment
  1356. {
  1357. $table = new DataTable();
  1358. $table->setMaximumAllowedRows($maxSubtableRows);
  1359. $table->metadata[self::COLUMN_AGGREGATION_OPS_METADATA_NAME]
  1360. = $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME);
  1361. $next->setSubtable($table);
  1362. // Summary row, has no metadata
  1363. $next->deleteMetadata();
  1364. }
  1365. }
  1366. }
  1367. return array($next, $i);
  1368. }
  1369. /**
  1370. * Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables.
  1371. *
  1372. * @param string|bool $labelColumn If supplied the label of the parent row will be added to
  1373. * a new column in each subtable row.
  1374. *
  1375. * If set to, `'label'` each subtable row's label will be prepended
  1376. * w/ the parent row's label. So `'child_label'` becomes
  1377. * `'parent_label - child_label'`.
  1378. * @param bool $useMetadataColumn If true and if `$labelColumn` is supplied, the parent row's
  1379. * label will be added as metadata and not a new column.
  1380. * @return \Piwik\DataTable
  1381. */
  1382. public function mergeSubtables($labelColumn = false, $useMetadataColumn = false)
  1383. {
  1384. $result = new DataTable();
  1385. foreach ($this->getRows() as $row) {
  1386. $subtable = $row->getSubtable();
  1387. if ($subtable !== false) {
  1388. $parentLabel = $row->getColumn('label');
  1389. // add a copy of each subtable row to the new datatable
  1390. foreach ($subtable->getRows() as $id => $subRow) {
  1391. $copy = clone $subRow;
  1392. // if the summary row, add it to the existing summary row (or add a new one)
  1393. if ($id == self::ID_SUMMARY_ROW) {
  1394. $existing = $result->getRowFromId(self::ID_SUMMARY_ROW);
  1395. if ($existing === false) {
  1396. $result->addSummaryRow($copy);
  1397. } else {
  1398. $existing->sumRow($copy, $copyMeta = true, $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME));
  1399. }
  1400. } else {
  1401. if ($labelColumn !== false) {
  1402. // if we're modifying the subtable's rows' label column, then we make
  1403. // sure to prepend the existing label w/ the parent row's label. otherwise
  1404. // we're just adding the parent row's label as a new column/metadata.
  1405. $newLabel = $parentLabel;
  1406. if ($labelColumn == 'label') {
  1407. $newLabel .= ' - ' . $copy->getColumn('label');
  1408. }
  1409. // modify the child row's label or add new column/metadata
  1410. if ($useMetadataColumn) {
  1411. $copy->setMetadata($labelColumn, $newLabel);
  1412. } else {
  1413. $copy->setColumn($labelColumn, $newLabel);
  1414. }
  1415. }
  1416. $result->addRow($copy);
  1417. }
  1418. }
  1419. }
  1420. }
  1421. return $result;
  1422. }
  1423. /**
  1424. * Returns a new DataTable created with data from a 'simple' array.
  1425. *
  1426. * See {@link addRowsFromSimpleArray()}.
  1427. *
  1428. * @param array $array
  1429. * @return \Piwik\DataTable
  1430. */
  1431. public static function makeFromSimpleArray($array)
  1432. {
  1433. $dataTable = new DataTable();
  1434. $dataTable->addRowsFromSimpleArray($array);
  1435. return $dataTable;
  1436. }
  1437. /**
  1438. * Creates a new DataTable instance from a serialized DataTable string.
  1439. *
  1440. * See {@link getSerialized()} and {@link addRowsFromSerializedArray()}
  1441. * for more information on DataTable serialization.
  1442. *
  1443. * @param string $data
  1444. * @return \Piwik\DataTable
  1445. */
  1446. public static function fromSerializedArray($data)
  1447. {
  1448. $result = new DataTable();
  1449. $result->addRowsFromSerializedArray($data);
  1450. return $result;
  1451. }
  1452. /**
  1453. * Aggregates the $row columns to this table.
  1454. *
  1455. * $row must have a column "label". The $row will be summed to this table's row with the same label.
  1456. *
  1457. * @param $row
  1458. * @throws \Exception
  1459. */
  1460. protected function aggregateRowWithLabel(Row $row, $doAggregateSubTables = true)
  1461. {
  1462. $labelToLookFor = $row->getColumn('label');
  1463. if ($labelToLookFor === false) {
  1464. throw new Exception("Label column not found in the table to add in addDataTable()");
  1465. }
  1466. $rowFound = $this->getRowFromLabel($labelToLookFor);
  1467. if ($rowFound === false) {
  1468. if ($labelToLookFor === self::LABEL_SUMMARY_ROW) {
  1469. $this->addSummaryRow($row);
  1470. } else {
  1471. $this->addRow($row);
  1472. }
  1473. } else {
  1474. $rowFound->sumRow($row, $copyMeta = true, $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME));
  1475. if($doAggregateSubTables) {
  1476. // if the row to add has a subtable whereas the current row doesn't
  1477. // we simply add it (cloning the subtable)
  1478. // if the row has the subtable already
  1479. // then we have to recursively sum the subtables
  1480. if (($idSubTable = $row->getIdSubDataTable()) !== null) {
  1481. $subTable = Manager::getInstance()->getTable($idSubTable);
  1482. $subTable->metadata[self::COLUMN_AGGREGATION_OPS_METADATA_NAME]
  1483. = $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME);
  1484. $rowFound->sumSubtable($subTable);
  1485. }
  1486. }
  1487. }
  1488. }
  1489. /**
  1490. * @param $row
  1491. */
  1492. protected function aggregateRowFromSimpleTable($row)
  1493. {
  1494. if ($row === false) {
  1495. return;
  1496. }
  1497. $thisRow = $this->getFirstRow();
  1498. if ($thisRow === false) {
  1499. $thisRow = new Row;
  1500. $this->addRow($thisRow);
  1501. }
  1502. $thisRow->sumRow($row, $copyMeta = true, $this->getMetadata(self::COLUMN_AGGREGATION_OPS_METADATA_NAME));
  1503. }
  1504. /**
  1505. * Unsets all queued filters.
  1506. */
  1507. public function clearQueuedFilters()
  1508. {
  1509. $this->queuedFilters = array();
  1510. }
  1511. /**
  1512. * @return \ArrayIterator|Row[]
  1513. */
  1514. public function getIterator() {
  1515. return new \ArrayIterator($this->getRows());
  1516. }
  1517. public function offsetExists($offset)
  1518. {
  1519. $row = $this->getRowFromId($offset);
  1520. return false !== $row;
  1521. }
  1522. public function offsetGet($offset)
  1523. {
  1524. return $this->getRowFromId($offset);
  1525. }
  1526. public function offsetSet($offset, $value)
  1527. {
  1528. $this->rows[$offset] = $value;
  1529. }
  1530. public function offsetUnset($offset)
  1531. {
  1532. $this->deleteRow($offset);
  1533. }
  1534. }