<?php
if (!defined('SORT_NATURAL')) {
define('SORT_NATURAL', 6);
}
if (!defined('SORT_FLAG_CASE')) {
define('SORT_FLAG_CASE', 8);
}
/**
* SimpleCollection.class.php
* collection of assoc arrays with convenience
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*
* @author André Noack <noack@data-quest.de>
* @copyright 2013 Stud.IP Core-Group
* @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
* @category Stud.IP
*
* @template T
*/
class SimpleCollection extends StudipArrayObject
{
/**
* callable to initialize collection
*
* @var ?callable(): array<T>
*/
protected $finder;
/**
* number of records after last init
*
* @var int
*/
protected $last_count;
/**
* collection with deleted records
* @var static
*/
protected $deleted;
/**
* creates a collection from an array of arrays
* all arrays should contain same keys, but is not enforced
*
* @param array<T> $data array containing assoc arrays
* @return SimpleCollection<T>
*/
public static function createFromArray(array $data)
{
return new self($data);
}
/**
* converts arrays or objects to ArrayObject objects
* if ArrayAccess interface is not available
*
* @param mixed $a
* @return StudipArrayObject|ArrayAccess
*/
public static function arrayToArrayObject($a)
{
if ($a instanceof StudipArrayObject) {
$a->setFlags(StudipArrayObject::ARRAY_AS_PROPS);
return $a;
}
if ($a instanceof ArrayObject) {
return new StudipArrayObject($a->getArrayCopy(), StudipArrayObject::ARRAY_AS_PROPS);
}
if ($a instanceof ArrayAccess) {
return $a;
}
return new StudipArrayObject((array) $a, StudipArrayObject::ARRAY_AS_PROPS);
}
/**
* returns closure to compare a value against given arguments
* using given operator
*
* @param string|callable(mixed, mixed|array): bool $operator
* @param mixed|array $args
* @throws InvalidArgumentException
* @return callable(mixed): bool comparison function
*/
public static function getCompFunc($operator, $args)
{
if (is_callable($operator)) {
$comp_func = function ($a) use ($args, $operator) {
return $operator($a, $args);
};
} else {
if (!is_array($args)) {
$args = [$args];
}
switch ($operator) {
case '==':
$comp_func = function ($a) use ($args) {
return in_array($a, $args);
};
break;
case '===':
$comp_func = function ($a) use ($args) {
return in_array($a, $args, true);
};
break;
case '!=':
case '<>':
$comp_func = function ($a) use ($args) {
return !in_array($a, $args);
};
break;
case '!==':
$comp_func = function ($a) use ($args) {
return !in_array($a, $args, true);
};
break;
case '<':
case '>':
case '<=':
case '>=':
$op_func = function ($a, $b) use ($operator) {
if ($operator === '<') {
return $a < $b;
} elseif ($operator === '<=') {
return $a <= $b;
} elseif ($operator === '>=') {
return $a >= $b;
} elseif ($operator === '>') {
return $a > $b;
}
};
$comp_func = function ($a) use ($op_func, $args) {
return $op_func($a, $args[0]);
};
break;
case '><':
$comp_func = function ($a) use ($args) {
return $a > $args[0] && $a < $args[1];
};
break;
case '>=<=':
$comp_func = function ($a) use ($args) {
return $a >= $args[0] && $a <= $args[1];
};
break;
case '%=':
$comp_func = function ($a) use ($args) {
$a = mb_strtolower(static::translitLatin1($a));
$args = array_map([static::class, 'translitLatin1'], $args);
$args = array_map('mb_strtolower', $args);
return in_array($a, $args);
};
break;
case '*=':
$comp_func = function ($a) use ($args) {
foreach ($args as $arg) {
if (mb_strpos($a, $arg) !== false) {
return true;
}
}
return false;
};
break;
case '^=':
$comp_func = function ($a) use ($args) {
foreach ($args as $arg) {
if (mb_strpos($a, $arg) === 0) {
return true;
}
}
return false;
};
break;
case '$=':
$comp_func = function ($a) use ($args) {
foreach ($args as $arg) {
$found = mb_strrpos($a, $arg);
if ($found !== false && ($found + mb_strlen($arg)) === mb_strlen($a)) {
return true;
}
}
return false;
};
break;
case '~=':
$comp_func = function ($a) use ($args) {
foreach ($args as $arg) {
if (preg_match($arg, $a) === 1) {
return true;
}
}
return false;
};
break;
default:
throw new InvalidArgumentException('unknown operator: ' . $operator);
}
}
return $comp_func;
}
/**
* transliterates latin1 string to ascii
*
* @param string $text
* @return string
*/
public static function translitLatin1($text)
{
if (!preg_match('/[\200-\377]/', $text)) {
return $text;
}
$text = str_replace(['ä','Ä','ö','Ö','ü','Ü','ß'], ['a','A','o','O','u','U','s'], $text);
$text = str_replace(['À','Á','Â','Ã','Å','Æ'], 'A' , $text);
$text = str_replace(['à','á','â','ã','å','æ'], 'a' , $text);
$text = str_replace(['È','É','Ê','Ë'], 'E' , $text);
$text = str_replace(['è','é','ê','ë'], 'e' , $text);
$text = str_replace(['Ì','Í','Î','Ï'], 'I' , $text);
$text = str_replace(['ì','í','î','ï'], 'i' , $text);
$text = str_replace(['Ò','Ó','Õ','Ô','Ø'], 'O' , $text);
$text = str_replace(['ò','ó','ô','õ','ø'], 'o' , $text);
$text = str_replace(['Ù','Ú','Û'], 'U' , $text);
$text = str_replace(['ù','ú','û'], 'u' , $text);
$text = str_replace(['Ç','ç','Ð','Ñ','Ý','ñ','ý','ÿ'], ['C','c','D','N','Y','n','y','y'] , $text);
return $text;
}
/**
* Constructor
*
* @param array<T>|callable(): array<T> $data array or closure to fill collection
*/
public function __construct($data = [])
{
parent::__construct();
$this->finder = is_callable($data) ? $data : null;
$this->deleted = clone $this;
if (is_callable($data)) {
$this->refresh();
} else {
$this->exchangeArray($data);
}
}
/**
* @param array $input
* @return array
*/
public function exchangeArray($input)
{
return parent::exchangeArray(array_map(
[static::class, 'arrayToArrayObject'],
$input
));
}
/**
* converts the object and all elements to plain arrays
*
* @return array
*/
public function toArray()
{
$args = func_get_args();
return $this->map(function ($a) use ($args) {
if (method_exists($a, 'toArray')) {
return call_user_func_array([$a, 'toArray'], $args);
}
if (method_exists($a, 'getArrayCopy')) {
return $a->getArrayCopy();
}
return (array) $a;
}
);
}
/**
*
* @see ArrayObject::append()
*/
public function append($newval)
{
parent::append(static::arrayToArrayObject($newval));
}
/**
* Sets the value at the specified index
* ensures the value has ArrayAccess
*
* @param mixed $index
* @param mixed $newval
*
* @see ArrayObject::offsetSet()
*/
public function offsetSet($index, $newval): void
{
if (is_numeric($index)) {
$index = (int) $index;
}
parent::offsetSet($index, static::arrayToArrayObject($newval));
}
/**
* Unsets the value at the specified index
* value is moved to internal deleted collection
*
* @see ArrayObject::offsetUnset()
* @throws InvalidArgumentException
*/
public function offsetUnset($index): void
{
if ($this->offsetExists($index)) {
$this->deleted[] = $this->offsetGet($index);
}
parent::offsetUnset($index);
}
/**
* sets the finder function
*
* @param callable(): array<T> $finder
* @return void
*/
public function setFinder(callable $finder)
{
$this->finder = $finder;
}
/**
* get deleted records collection
* @return SimpleCollection<T>
*/
public function getDeleted()
{
return $this->deleted;
}
/**
* reloads the elements of the collection
* by calling the finder function
*
* @return ?int of records after refresh
*/
public function refresh()
{
if (is_callable($this->finder)) {
$data = call_user_func($this->finder);
$this->exchangeArray($data);
$this->deleted->exchangeArray([]);
return $this->last_count = $this->count();
}
}
/**
* returns a new collection containing all elements
* where given columns value matches given value(s) using passed operator
* pass array for multiple values
*
* operators:
* == equal, like php
* === identical, like php
* !=,<> not equal, like php
* !== not identical, like php
* <,>,<=,>= less,greater,less or equal,greater or equal
* >< between without borders, needs two arguments
* >=<= between including borders, needs two arguments
* %= like string, transliterate to ascii,case insensitive
* *= contains string
* ^= begins with string
* $= ends with string
* ~= regex
*
* @param string $key the column name
* @param mixed $values value to search for
* @param string|callable $op operator to find
* @return SimpleCollection<T> with found records
*/
public function findBy($key, $values, $op = '==')
{
$comp_func = self::getCompFunc($op, $values);
return $this->filter(function ($record) use ($comp_func, $key) {
return $comp_func($record[$key]);
});
}
/**
* returns the first element
* where given column has given value(s)
* pass array for multiple values
*
* @param string $key the column name
* @param mixed $values value to search for,
* @param string|callable $op operator to find
* @return ?T found record
*/
public function findOneBy($key, $values, $op = '==')
{
$comp_func = self::getCompFunc($op, $values);
return $this->filter(function ($record) use ($comp_func, $key) {
return $comp_func($record[$key]);
}, 1)->first();
}
/**
* apply given callback to all elements of
* collection
*
* @param callable(T): int $func the function to call
* @return int|false addition of return values
*/
public function each(callable $func)
{
$result = false;
foreach ($this->storage as $record) {
$result += call_user_func($func, $record);
}
return $result;
}
/**
* apply given callback to all elements of
* collection and give back array of return values
*
* @param callable(T, mixed): mixed $func the function to call
* @return array<mixed>
*/
public function map(callable $func)
{
$results = [];
foreach ($this->storage as $key => $value) {
$results[$key] = call_user_func($func, $value, $key);
}
return $results;
}
/**
* filter elements
* if given callback returns true
*
* @param ?callable(T, mixed): bool $func the function to call
* @param ?integer $limit limit number of found records
* @return SimpleCollection<T> containing filtered elements
*/
public function filter(callable $func = null, $limit = null)
{
$results = [];
$found = 0;
foreach ($this->storage as $key => $value) {
if (call_user_func($func, $value, $key)) {
$results[$key] = $value;
if ($limit && (++$found == $limit)) {
break;
}
}
}
return self::createFromArray($results);
}
/**
* Returns whether any element of the collection returns true for the
* given callback.
*
* @param callable(T, mixed): bool $func the function to call
* @return bool
*/
public function any(callable $func)
{
foreach ($this->storage as $key => $value) {
if (call_user_func($func, $value, $key)) {
return true;
}
}
return false;
}
/**
* Returns whether every element of the collection returns true for the
* given callback.
*
* @param callable(T, mixed): bool $func the function to call
* @return bool
*/
public function every(callable $func)
{
foreach ($this->storage as $key => $value) {
if (!call_user_func($func, $value, $key)) {
return false;
}
}
return true;
}
/**
* extract array of columns values
* pass array or space-delimited string for multiple columns
*
* @param string|array $columns the column(s) to extract
* @return array of extracted values
*/
public function pluck($columns)
{
if (!is_array($columns)) {
$columns = words($columns);
}
$func = function ($r) use ($columns) {
$result = [];
foreach ($columns as $c) {
$result[] = $r[$c];
}
return $result;
};
$result = $this->map($func);
return count($columns) === 1 ? array_map('current', $result) : $result;
}
/**
* returns the collection as grouped array
* first param is the column to group by, it becomes the key in
* the resulting array, default is pk. Limit returned fields with second param
* The grouped entries can optoionally go through the given
* callback. If no callback is provided, only the first grouped
* entry is returned, suitable for grouping by unique column
*
* @param string $group_by the column to group by, pk if ommitted
* @param string|array|null $only_these_fields limit returned fields
* @param ?callable $group_func closure to aggregate grouped entries
* @return array assoc array
*/
public function toGroupedArray($group_by = 'id', $only_these_fields = null, callable $group_func = null)
{
$result = [];
if (is_string($only_these_fields)) {
$only_these_fields = words($only_these_fields);
}
foreach ($this->toArray() as $record) {
$key = $record[$group_by];
$ret = [];
if (is_array($only_these_fields)) {
$result[$key][] = array_intersect_key($record, array_flip($only_these_fields));
} else {
$result[$key][] = $record;
}
}
if ($group_func === null) {
$group_func = 'current';
}
return array_map($group_func, $result);
}
/**
* get the first element
*
* @return ?T first element or null
*/
public function first()
{
$keys = array_keys($this->storage);
$first_offset = reset($keys);
return $this->offsetGet($first_offset ?: 0);
}
/**
* get the last element
*
* @return ?T last element or null
*/
public function last()
{
$keys = array_keys($this->storage);
$last_offset = end($keys);
return $this->offsetGet($last_offset ?: 0);
}
/**
* get the the value from given key from first element
*
* @param string $key
* @return mixed
*/
public function val($key)
{
$first = $this->first();
return $first[$key] ?? null;
}
/**
* mark element(s) for deletion
* where given column has given value(s)
* element(s) are moved to
* internal deleted collection
* pass array for multiple values
*
* operators:
* == equal, like php
* === identical, like php
* !=,<> not equal, like php
* !== not identical, like php
* <,>,<=,>= less,greater,less or equal,greater or equal
* >< between without borders, needs two arguments
* >=<= between including borders, needs two arguments
* %= like string, transliterate to ascii,case insensitive
* *= contains string
* ^= begins with string
* $= ends with string
* ~= regex
*
* @param string $key
* @param mixed $values
* @param string|callable(mixed, mixed|array): bool $op operator to find elements
* @return int|false number of unsetted elements
*/
public function unsetBy($key, $values, $op = '==')
{
$ret = false;
$comp_func = self::getCompFunc($op, $values);
foreach ($this->storage as $k => $record) {
if ($comp_func($record[$key])) {
$this->offsetunset($k);
$ret += 1;
}
}
return $ret;
}
/**
* sorts the collection by columns of contained elements and returns it
*
* works like sql order by:
* first param is a string containing combinations of column names
* and sort direction, separated by comma e.g.
* 'name asc, nummer desc '
* sorts first by name ascending and then by nummer descending
* second param denotes the sort type (using PHP sort constants):
* SORT_LOCALE_STRING:
* compare items as strings, transliterate latin1 to ascii, case insensitiv, natural order for numbers
* SORT_NUMERIC:
* compare items as integers
* SORT_STRING:
* compare items as strings
* SORT_NATURAL:
* compare items as strings using "natural ordering"
* SORT_FLAG_CASE:
* can be combined (bitwise OR) with SORT_STRING or SORT_NATURAL to sort strings case-insensitively
*
* @param string $order columns to order by
* @param integer $sort_flags
* @return $this the sorted collection
*/
public function orderBy($order, $sort_flags = SORT_LOCALE_STRING)
{
//('name asc, nummer desc ')
$sort_locale = false;
switch ($sort_flags) {
case SORT_NATURAL:
$sort_func = 'strnatcmp';
break;
case SORT_NATURAL | SORT_FLAG_CASE:
$sort_func = 'strnatcasecmp';
break;
case SORT_STRING | SORT_FLAG_CASE:
$sort_func = 'strcasecmp';
break;
case SORT_STRING:
$sort_func = 'strcmp';
break;
case SORT_NUMERIC:
$sort_func = function ($a, $b) {
return (int) $a - (int) $b;
};
break;
case SORT_LOCALE_STRING:
default:
$sort_func = 'strnatcasecmp';
$sort_locale = true;
}
$sorter = [];
foreach (explode(',', $order) as $one) {
$sorter[] = array_values(array_filter(array_map('trim', explode(' ', $one))));
}
$func = function ($d1, $d2) use ($sorter, $sort_func, $sort_locale) {
do {
$current_sorter = current($sorter);
$field = $current_sorter[0];
$dir = $current_sorter[1] ?? '';
if (!$sort_locale) {
$value1 = $d1[$field];
$value2 = $d2[$field];
} else {
$value1 = static::translitLatin1(mb_substr($d1[$field], 0, 100));
$value2 = static::translitLatin1(mb_substr($d2[$field], 0, 100));
}
$ret = $sort_func($value1, $value2);
if (strtolower($dir) == 'desc') $ret = $ret * -1;
} while ($ret === 0 && next($sorter));
return $ret;
};
if (count($sorter)) {
$this->uasort($func);
}
return $this;
}
/**
* returns a new collection contaning a sequence of original collection
* mimics the sql limit constrain:
* used with one parameter, the first x elements are extracted
* used with two parameters, the first parameter denotes the offset, the second the
* number of elements
*
* @param integer $arg1
* @param ?integer $arg2
* @return SimpleCollection<T>
*/
public function limit($arg1, $arg2 = null)
{
if (is_null($arg2)) {
if ($arg1 > 0) {
$row_count = $arg1;
$offset = 0;
} else {
$row_count = abs($arg1);
$offset = $arg1;
}
} else {
$offset = $arg1;
$row_count = $arg2;
}
return self::createFromArray(array_slice($this->storage, $offset, $row_count, true));
}
/**
* calls the given method on all elements
* of the collection
* @param literal-string $method methodname to call
* @param array $params parameters for methodcall
* @return array of all return values
*/
public function sendMessage($method, $params = []) {
$results = [];
foreach ($this->storage as $record) {
$results[] = call_user_func_array([$record, $method], $params);
}
return $results;
}
/**
* magic version of sendMessage
* calls undefineds methods on all elements of the collection
* But beware of the dark side...
*
* @param literal-string $method methodname to call
* @param array $params parameters for methodcall
* @return array of all return values
*/
public function __call($method, $params)
{
return $this->sendMessage($method, $params);
}
/**
* merge in another collection, elements are appended
*
* @param SimpleCollection<T> $a_collection
* @return void
*/
public function merge(SimpleCollection $a_collection)
{
$this->storage = array_merge($this->storage, $a_collection->getArrayCopy());
}
}