Collector¶

A collector class is designed to hold and manage multiple items. An item can be an other collector or an calculator object.

Default Collectors¶

phpReport has a very powerful feature to aggregate values and increment counters. Each value and counter is implemented as a calculator object. These objects will be assigned to one collector.

phpReport instantiates the following collectors.

Note

All entities assigned to one of those collectors are cumulated to higher group levels.

Row counter collector¶

The row counter collector is named rc. For each data dimension one CalculatorXS object will be instantiated.

Group counter collector¶

The group counter collector is named gc. For each defined group one CalculatorXS object will be instantiated.

Total collector¶

The total collector is named total. The collector is used to hold all calculator objects instantiated by the compute() method and the sheet objects instantiated by the sheet() method.

You can assign further collectors, sheets or calculators to this total collector or any other collector in this tree. So it’s possible to build a hirachichal structure of aggregated values.

Row counter¶

phpReport always counts all read data rows.

For each data dimension one CalculatorXS object will be instantiated as an item within an collector named rc.

Using the same objects for incrementing counters as calculating any values provides you the same methods for accessing the results. This includes also that row counters are available at each group level.

Note

Only the last data diminsion has counters for all group levels. First data dimensions serve counters down to the group(s) declared in it.

$this->rep = new Report();
//
// Some code here ...
//
$this->rep->rc->items[*dimensionID*]->sum(*level*).

Example:

$this->rep = new Report();
$rc = $this->rep->rc;
// sum of rows read in all data dimensions at the current group level
$rc->sum();
// sum of rows read in all data dimensions at group level = 2
$rc->sum(2);
// sum of rows read in data dimensions 0 at current group level
$rep->rc->{0}->sum();
$rep->rc->items[0]->sum();     // That's the same
// sum of rows read in data dimensions 1 at group level = 2
$rep->rc->{1}->sum(2);
$rep->rc->items[1]->sum(2);     // That's the same

Group counter¶

As soon as you declare a group phpReport counts how often this group occurs in the higher goup level. In other words we count how many different values of a certain group has been processed.

For each group one CalculatorXS object will be instantiated as an item within an collector named gc.

Group counters are, like any other aggregation methods, available at each group level.

Attention

Make sure you access the correct gc item. To get the counter of the current group use the item of the previous group.

Tip

Use a negative value for the group level. -1 means the level above the current level.

$this->rep = new Report();
//
// Some code here ...
//
$this->rep->gc->items[*group*]->sum(*level*).

Example:

$this->rep = new Report();
$gc = $this->rep->gc;
// Sum of group in the group above the current group.
$gc->sum(-1);
// sum of group  data dimensions at group level = 2
$rc->sum(2);
// sum of rows read in data dimensions 0 at current group level
$rep->rc->{0}->sum();
$rep->rc->items[0]->sum();     // That's the same
// sum of rows read in data dimensions 1 at group level = 2
$rep->rc->{1}->sum(2);
$rep->rc->items[1]->sum(2);     // That's the same

The main responsibilty of an collector is to call methods in assigned items. To make sure that the cumputation of calculated values works correct calculator objects must be registered to the total collector or to one of his child collectors.

The collector class has the ArrayAccess interface and the magic __get method implemented which allows a broad range of access options.

The visibility of the $items array is public. This allows maximum speed when accessing an item and gives the opportunity to apply all php array methods.

Add items¶

Items will be added (or registered) to an collector usually by calling the calculate() or sheet() methods of the phpReport class.

You may can also add items by the addItem() method. This is especially desired when you want to group multiple item objects.

Adding items to a sheet collector is hidden and will be internally handled based on key values of the add() method.

Alternate item keys¶

Items are stored in the $item array indexed by the name given when calling the addItem() method. You can also apply an alternate key to allow accessing an item by the alternate key as well.

The setAltKeys() method will set many alternate keys while the setAltKey() method one alternate key.

The group conter collecor uses alternate keys to allow accessing the counters by the group level and by the group name.

Get items¶

To access an item you can use the getItems() method for all items or the getItem() method to get one item.

The magic __get() and the array access get methods calls the getItem() method. The item will returned when it exist either by the item array key or by the alternate key.

$this->rep = new phpReport($this);
$this->rep->compute('sales');
// All of the following statements will return the same item.
$item = $this->report->total->getItem('sales');
$item = $this->report->total->items['sales']);
$item = $this->report->total->sales;
$item = $this->report->total['sales'];

Aggregate methods¶

All aggregate methods implemented in the calculator classes have their counterpart it the collector classes.

The collector aggregate methods calls the same methods for each assigned item. Returned results will be returned either as an array indexed by the item key or as an scalar aggregated value.

Subset of items¶

To apply aggregate methods only on some items you can build a subset by calling the following filter methods. Each of them will return a cloned collector object with just the filtered items.

To use the cloned collector multiple times hold the reference to the cloned collector in a variable.

range(...$ranges): AbstractCollecotor

Extract ranges of items.

Returns ranges of items located between start and end keys.

When a range is an array value1 is the start and value2 the end key. When one of the keys don’t exist the value of the altKey will be used instead. When the items still doesn’t exist an error will be thrown.

If start key equals Null the range begins at the first item. When the end key equals Null the range ends at the last item.

When a range is not an array then the item with the corresponding key or altKey is returned if it exist. If this doesn’t exist php raise a notice.

Item keys are preserved. Sort order within ranges are preserved. Ranges are returned in given order. When items belong to multiple ranges only the first occurence will returned.

:param array|int|string[] $ranges Ranges or item keys for items to be filtered. :return AbstractCollector Cloned collector with items in ranges. :throws InvalidArgumentException When start or end item doesn’t exist.

between(...$ranges): AbstractCollecotor

Filters items where key is between values.

Iterates over each collector item. If a range is an array and the item key is between value1 and value2 of this range (inclusive) the item is returned.

If the range isn’t an the item with the corresponding key is returned.

If a range matches the key of a named range then the named range value will be used to filter the items.

Item keys and sort order are preserved.

Parameters

array|int|string[] – $ranges Ranges or item keys for items to be filtered.

Returns

AbstractCollector Cloned collector with items in ranges.

filter(callable $callable):

Filters items using a callback function. Iterates over each item in the array passing key and value to the callback function. If the callback function returns TRUE, the current item is returned into the cloned collector. Item keys are preserved.

Parameters

$callable (callable) – The callback function to use.

Returns

AbstractCollector Clone of current collector with filtered items

cmd(callable $command, ...$params): AbstractCollector

Alter item collection by executing a php array command.

Parameters

$command (callable) – Any php array command which accepts an array as the first parameter.
$params (mixed[]) – Additional parameters passed to the php command.

Returns

AbstractCollector Clone of current collector with applied command on the items array.

More specific groups¶

To build even more specific groups of calculators instantiate a new collector and add any items (calculator or collector) to this collector. To make sure that the values within the calculators are properly set use only already instanted calculators.