New interfaces for collector classes

Author: gpoehl

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "gpoehl/phpreport",
-     "description": "PHP library solving almost all common tasks for applications working with data groups. It manages group changes, provides aggregate functions and can even join data from different sources.",
+    "description": "PHP library solving almost all common tasks for applications working with data sets. It manages group changes, provides aggregate functions and can even join data from different sources.",
     "license": "LGPL-3.0-or-later",
     "authors": [
         {
@@ -10,18 +10,17 @@
     "keywords": [
         "php",
         "report",
+		"reporting"
         "grouping",
-        "group change",
         "totals",
         "subtotals",
-        "sheets",
-        "join"
+        "sheets"   
     ],
     "archive": {
         "exclude": ["/docs",  "/docs/build"]
     },
     "require": {
-        "php": "^7.4"
+        "php": ">=7.4"
     },
     "autoload": {
         "classmap": [

docs/source/collector.rst

@@ -1,61 +1,145 @@
 Collector
 =========
 
-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.
+A collector class is designed to hold and manage multiple items. An item can 
+be an other collector or an calculator object.
 
-phpReport instantiates the following collectors. 
+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. 
 
-.. note::
-    All entities assigned to one of those collectors are cumulated to 
-    higher group levels.
+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. 
 
-Row counter collector
-----------------------
 
-The row counter collector is named **rc**. For each data dimension one CalculatorXS
-object will be instantiated.
+Add items
+---------
 
-Group counter collector
------------------------
+Items will be added (or registered) to an collector usually by calling the calculate()
+or sheet() methods of the **phpReport** class.
 
-The group counter collector is named **gc**. For each defined group one CalculatorXS
-object will be instantiated.
+You may can also add items by the addItem() method. This is especially desired when
+you want to group multiple item objects. 
 
-Total collector
----------------
+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 total collector is named **total**. The collector is used to hold all calculator
-objects instantiated by the aggregate() method and the sheet objects instantiated
-by the sheet() method.
+The setAltKeys() method will set many alternate keys while the setAltKey()
+method one alternate key.
 
-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.
+The group conter collecor uses alternate keys to allow accessing the counters
+by the group level and by the group name.
 
 
-Accessing values
-----------------
+Get items
+---------
 
-There are multiple options to access a calculater object. The long version looks
-like
+To access an item you can use the getItems() method for all items or the getItem()
+method to get one item. 
 
-$this->rep->*collectorName*->items[*itemName*].
+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.
 
 .. code-block:: php
 
-    $rep = $this->report;
-    $rep->t->*name*; 
-    $rep->t['*name*'];
-    $rep->rc;
-    $rep->rc->{0};
-    $rep->rc->[0];
- 
-.. include:: rowCounter.rst
-.. include:: groupCounter.rst
+    $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
+-----------------
 
-Range of values
+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 funcions only to a subset of collected items use the range method. 
+
+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. 
+
+.. php:method:: 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.
+
+.. php:method:: 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.
+ 
+    :param array|int|string[]: $ranges Ranges or item keys for items to be filtered.
+    :returns: AbstractCollector Cloned collector with items in ranges.
+
+.. php:method:: 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.
+ 
+    :param callable $callable: The callback function to use. 
+    :returns: AbstractCollector Clone of current collector with filtered items
+
+.. php:method:: cmd(callable $command, ...$params): AbstractCollector
+
+    Alter item collection by executing a php array command.
+ 
+    :param callable $command: Any php array command which accepts an 
+      array as the first parameter. 
+    :param mixed[] $params: Additional parameters passed to the php command.
+    :returns: AbstractCollector Clone of current collector with applied command
+      on the items array. 

docs/source/conf.py

@@ -32,7 +32,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        'sphinx.ext.todo',
+    'sphinx.ext.todo',
 	'sphinx_rtd_theme',
 	'sphinxcontrib.phpdomain',
 ]
@@ -68,7 +68,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 html_context = {
 	# Enable the "Edit in GitHub link within the header of each page.

docs/source/defaultCollectors.rst

@@ -0,0 +1,39 @@
+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.
+
+.. include:: rowCounter.rst
+.. include:: groupCounter.rst

src/AbstractCalculator.php

@@ -13,6 +13,7 @@
 
 namespace gpoehl\phpReport;
 
+
 /**
  * Base class for calculator classes.
  */

src/AbstractCollector.php

@@ -53,13 +53,15 @@ public function setAltKey($key, $itemKey): void {
 
     /**
      * Magic get method to access item via arrow notation.
+     * Note: A magic setter method is not implemented. Use the addItem method instead.
      * Example: $collector->itemKey 
      * @param int|string $key the item key 
      * @return AbstractCollector|AbstractCalculator Returns the requested item
      */
     public function __get($key): object {
         return $this->getItem($key);
     }
+    
 
     /* -------------------------------------------------------------------------
      * Implementation of the arrayAccess interface
@@ -167,7 +169,7 @@ public function cumulateToNextLevel(): void {
      * @return AbstractCollector Clone of current collector with selected items.
      * @throws InvalidArgumentException When start or end item doesn't exist.
      */
-    public function range(... $ranges): AbstractCollector {
+    public function range(...$ranges): AbstractCollector {
         $collector = clone $this;
         $collector->items = [];
         $keyOffsets = array_flip(array_keys($this->items));
@@ -234,7 +236,7 @@ private function findItemKey($key) {
      * @param array|int|string[] $ranges Ranges or item keys for items to be filtered.
      * @return AbstractCollector Clone of current collector with filtered items.
      */
-    public function between(... $ranges): AbstractCollector {
+    public function between(...$ranges): AbstractCollector {
         $collector = clone $this;
         $collector->items = [];
         foreach ($this->items as $key => $item) {

src/Calculator.php

@@ -12,11 +12,12 @@
 
 namespace gpoehl\phpReport;
 
+
 /**
  * Summarize values and count how often not null and not zero values are given
  * to the add() method.
  */
-class Calculator extends AbstractCalculator {
+class Calculator extends AbstractCalculator implements NnAndNzCounterIF{
 
     /** @var int[] not null counter. How many added values had a value not equal to zero. */
     protected $nn = [];
@@ -32,22 +33,6 @@ public function __construct(MajorProperties $mp, int $maxLevel) {
         $this->total = $this->nz = $this->nn = array_fill(0, $maxLevel + 1, 0);
     }
 
-    /**
-     * Returns always true. Counters for notNull and notZero values are implemented.  
-     * @return true
-     */
-    public function hasCounter(): bool {
-        return true;
-    }
-
-    /**
-     * Returns always false. Methods to handle min and max values are not implemented. 
-     * @return false
-     */
-    public function hasMinMax(): bool {
-        return false;
-    }
-
     /**
      * Add given $value to $maxLevel and increment counters.
      * @param numeric|null $value The numeric data value which will be added
@@ -88,7 +73,7 @@ public function cumulateToNextLevel(): void {
      * @return numeric The running total of added values from the requested level down
      * to the lowest level
      */
-    public function sum($level = null) {
+    public function sum(int $level = null) {
         return array_sum(array_slice($this->total, $this->mp->getLevel($level)));
     }
 
@@ -97,7 +82,7 @@ public function sum($level = null) {
      * @param int|null $level The requested level. Defaults to the current level.
      * @return int The total number of added not null values for the requested level.
      */
-    public function nn($level = null): int {
+    public function nn(int $level = null): int {
         // To calculate the total number all values from requested level down
         // to lowest level must be included.
         return array_sum(array_slice($this->nn, $this->mp->getLevel($level)));
@@ -109,7 +94,7 @@ public function nn($level = null): int {
      * @return int The total number of added not null and not zero values for 
      * the requested level.
      */
-    public function nz($level = null): int {
+    public function nz(int $level = null): int {
         // To calculate the total number all values from requested level down
         // to lowest level must be included.
         return array_sum(array_slice($this->nz, $this->mp->getLevel($level)));