<?php
/**
* SimpleORMapCollection.class.php
* simple object-relational mapping
*
* 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 2012 Stud.IP Core-Group
* @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
* @category Stud.IP
*
* @extends SimpleCollection<SimpleORMap>
*
* @template T of SimpleORMap
*/
class SimpleORMapCollection extends SimpleCollection
{
/**
* @var int Exception error code denoting a wrong type of objects.
*/
const WRONG_OBJECT_TYPE = 1;
/**
* @var int Exception error code denoting that an object of this `id` already exists.
*/
const OBJECT_EXISTS = 2;
/**
* the record object this collection belongs to
*
* @var ?SimpleORMap
*/
protected $related_record;
/**
* relation options
* @var array
*/
protected $relation_options = [];
/**
* creates a collection from an array of objects
* all objects should be of the same type
*
* @throws InvalidArgumentException if first entry is not SimpleOrMap
* @param T[] $data array with SimpleORMap objects
* @param bool $strict check every element for correct type and unique pk
* @return SimpleORMapCollection<T>
*/
public static function createFromArray(array $data, $strict = true)
{
$ret = new SimpleORMapCollection();
if (count($data)) {
$first = current($data);
if ($first instanceof SimpleORMap) {
$ret->setClassName(get_class($first));
if ($strict) {
foreach ($data as $one) {
$ret[] = $one;
}
} else {
$ret->exchangeArray($data);
}
} else {
throw new InvalidArgumentException('This collection only accepts objects derived from SimpleORMap', self::WRONG_OBJECT_TYPE);
}
}
return $ret;
}
/**
* Constructor
*
* @param ?Closure $finder callable to fill collection
* @param ?array $options relationship options
* @param SimpleORMap|null $record related record
*/
public function __construct(Closure $finder = null, array $options = null, SimpleORMap $record = null)
{
$this->relation_options = $options;
$this->related_record = $record;
parent::__construct($finder === null ? [] : $finder);
}
/**
* Sets the value at the specified index
* checks if the value is an object of specified class
*
* @see ArrayObject::offsetSet()
* @throws InvalidArgumentException if the given model does not fit (wrong type or id)
*/
public function offsetSet($index, $newval): void
{
if (!is_null($index)) {
$index = (int)$index;
}
if (!is_a($newval, $this->getClassName())) {
throw new InvalidArgumentException('This collection only accepts objects of type: ' . $this->getClassName(), self::WRONG_OBJECT_TYPE);
}
if ($this->related_record && $this->relation_options['type'] === 'has_many') {
$foreign_key_value = call_user_func($this->relation_options['assoc_func_params_func'], $this->related_record);
call_user_func($this->relation_options['assoc_foreign_key_setter'], $newval, $foreign_key_value);
}
if ($newval->id !== null) {
$exists = $this->find($newval->id);
if ($exists) {
throw new InvalidArgumentException('Element could not be appended, element with id: ' . $exists->id . ' is in the way', self::OBJECT_EXISTS);
}
}
parent::offsetSet($index, $newval);
}
/**
* sets the allowed class name
* @param class-string $class_name
* @return void
*/
public function setClassName($class_name)
{
$this->relation_options['class_name'] = strtolower($class_name);
$this->deleted->relation_options['class_name'] = strtolower($class_name);
}
/**
* sets the related record
*
* @param SimpleORMap $record
* @return void
*/
public function setRelatedRecord(SimpleORMap $record)
{
$this->related_record = $record;
}
/**
* gets the allowed classname
*
* @return string
*/
public function getClassName()
{
return strtolower($this->relation_options['class_name']);
}
/**
* reloads the elements of the collection
* by calling the finder function
*
* @throws InvalidArgumentException
* @return ?int number of records after refresh
*/
public function refresh()
{
if (is_callable($this->finder)) {
$data = call_user_func($this->finder, $this->related_record);
foreach ($data as $one) {
if (!is_a($one, $this->getClassName())) {
throw new InvalidArgumentException('This collection only accepts objects of type: ' . $this->getClassName(), self::WRONG_OBJECT_TYPE);
}
}
$this->exchangeArray($data);
$this->deleted->exchangeArray([]);
return $this->last_count = $this->count();
}
return null;
}
/**
* returns element with given primary key value
*
* @param string $value primary key value to search for
* @return ?T
*/
public function find($value)
{
return $this->findOneBy('id', $value);
}
/**
* 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 mixed $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 = [];
foreach ($this as $record) {
$key = $record->getValue($group_by);
if (is_array($key)) {
$key = join('_', $key);
}
$result[$key][] = $record->toArray($only_these_fields);
}
if ($group_func === null) {
$group_func = 'current';
}
return array_map($group_func, $result);
}
/**
* mark element(s) for deletion
* element(s) with given primary key are moved to
* internal deleted collection
*
* @param string $id primary key of element
* @return int number of unsetted elements
*/
public function unsetByPk($id)
{
return $this->unsetBy('id', $id);
}
/**
* merge in another collection, elements must be of
* the same type, if an element already exists it is
* replaced or ignored depending on second param
*
* @param SimpleORMapCollection $a_collection
* @param string $mode 'replace' or 'ignore'
* @return void
*/
public function merge(SimpleCollection $a_collection, string $mode = 'ignore')
{
$mode = func_get_arg(1);
foreach ($a_collection as $element) {
try {
/**
* @throws InvalidArgumentException
* @see SimpleORMapCollection::offsetSet()
*/
$this[] = $element;
} catch (InvalidArgumentException $e) {
if ($e->getCode() === self::OBJECT_EXISTS) {
if ($mode === 'replace') {
$this->unsetByPk($element->id);
$this[] = $element;
} // else $mode means 'ignore'
} else {
throw $e;
}
}
}
$this->storage = array_values($this->storage);
}
}