Skip to content
Snippets Groups Projects
Commit d62f1b74 authored by Marcus Eibrink-Lunzenauer's avatar Marcus Eibrink-Lunzenauer
Browse files

Korrektur und Verbesserung aller API-Dokumentationskommentare in SORM-bezogenen Klassen

parent 30fa5dcc
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
lib/classes/StudipPDO.class.php
+ 4
− 4
View file @ d62f1b74
...@@ -121,11 +121,11 @@ class StudipPDO extends PDO ...@@ -121,11 +121,11 @@ class StudipPDO extends PDO
* Quotes the given value in a form appropriate for the type. * Quotes the given value in a form appropriate for the type.
* If no explicit type is given, the value's PHP type is used. * If no explicit type is given, the value's PHP type is used.
* *
* @param mixed PHP value to quote * @param mixed $value PHP value to quote
* @param int parameter type (e.g. PDO::PARAM_STR) * @param ?int $type parameter type (e.g. PDO::PARAM_STR)
* @return string quoted SQL string * @return string quoted SQL string
*/ */
public function quote($value, $type = NULL) public function quote($value, $type = null)
{ {
if (!isset($type)) { if (!isset($type)) {
if (is_null($value)) { if (is_null($value)) {
......
lib/models/SimpleCollection.class.php
+ 59
− 53
View file @ d62f1b74
...@@ -19,13 +19,15 @@ if (!defined('SORT_FLAG_CASE')) { ...@@ -19,13 +19,15 @@ if (!defined('SORT_FLAG_CASE')) {
* @copyright 2013 Stud.IP Core-Group * @copyright 2013 Stud.IP Core-Group
* @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2 * @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
* @category Stud.IP * @category Stud.IP
*
* @template T
*/ */
class SimpleCollection extends StudipArrayObject class SimpleCollection extends StudipArrayObject
{ {
/** /**
* callable to initialize collection * callable to initialize collection
* *
* @var Closure * @var ?callable(): array<T>
*/ */
protected $finder; protected $finder;
...@@ -38,7 +40,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -38,7 +40,7 @@ class SimpleCollection extends StudipArrayObject
/** /**
* collection with deleted records * collection with deleted records
* @var SimpleCollection * @var static
*/ */
protected $deleted; protected $deleted;
...@@ -46,10 +48,10 @@ class SimpleCollection extends StudipArrayObject ...@@ -46,10 +48,10 @@ class SimpleCollection extends StudipArrayObject
* creates a collection from an array of arrays * creates a collection from an array of arrays
* all arrays should contain same keys, but is not enforced * all arrays should contain same keys, but is not enforced
* *
* @param array $data array containing assoc arrays * @param array<T> $data array containing assoc arrays
* @return SimpleCollection * @return SimpleCollection<T>
*/ */
public static function createFromArray(Array $data) public static function createFromArray(array $data)
{ {
return new self($data); return new self($data);
} }
...@@ -59,7 +61,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -59,7 +61,7 @@ class SimpleCollection extends StudipArrayObject
* if ArrayAccess interface is not available * if ArrayAccess interface is not available
* *
* @param mixed $a * @param mixed $a
* @return ArrayAccess * @return StudipArrayObject|ArrayAccess
*/ */
public static function arrayToArrayObject($a) public static function arrayToArrayObject($a)
{ {
...@@ -83,14 +85,14 @@ class SimpleCollection extends StudipArrayObject ...@@ -83,14 +85,14 @@ class SimpleCollection extends StudipArrayObject
* returns closure to compare a value against given arguments * returns closure to compare a value against given arguments
* using given operator * using given operator
* *
* @param string $operator * @param string|callable(mixed, mixed|array): bool $operator
* @param mixed $args * @param mixed|array $args
* @throws InvalidArgumentException * @throws InvalidArgumentException
* @return Closure comparison function * @return callable(mixed): bool comparison function
*/ */
public static function getCompFunc($operator, $args) public static function getCompFunc($operator, $args)
{ {
if ($operator instanceOf Closure) { if (is_callable($operator)) {
$comp_func = function ($a) use ($args, $operator) { $comp_func = function ($a) use ($args, $operator) {
return $operator($a, $args); return $operator($a, $args);
}; };
...@@ -234,14 +236,14 @@ class SimpleCollection extends StudipArrayObject ...@@ -234,14 +236,14 @@ class SimpleCollection extends StudipArrayObject
/** /**
* Constructor * Constructor
* *
* @param mixed $data array or closure to fill collection * @param array<T>|callable(): array<T> $data array or closure to fill collection
*/ */
public function __construct($data = []) public function __construct($data = [])
{ {
parent::__construct(); parent::__construct();
$this->finder = $data instanceof Closure ? $data : null; $this->finder = is_callable($data) ? $data : null;
$this->deleted = clone $this; $this->deleted = clone $this;
if ($data instanceof Closure) { if (is_callable($data)) {
$this->refresh(); $this->refresh();
} else { } else {
$this->exchangeArray($data); $this->exchangeArray($data);
...@@ -283,7 +285,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -283,7 +285,7 @@ class SimpleCollection extends StudipArrayObject
*/ */
public function append($newval) public function append($newval)
{ {
return parent::append(static::arrayToArrayObject($newval)); parent::append(static::arrayToArrayObject($newval));
} }
/** /**
...@@ -291,13 +293,14 @@ class SimpleCollection extends StudipArrayObject ...@@ -291,13 +293,14 @@ class SimpleCollection extends StudipArrayObject
* ensures the value has ArrayAccess * ensures the value has ArrayAccess
* *
* @see ArrayObject::offsetSet() * @see ArrayObject::offsetSet()
* @return void
*/ */
public function offsetSet($index, $newval) public function offsetSet($index, $newval)
{ {
if (is_numeric($index)) { if (is_numeric($index)) {
$index = (int) $index; $index = (int) $index;
} }
return parent::offsetSet($index, static::arrayToArrayObject($newval)); parent::offsetSet($index, static::arrayToArrayObject($newval));
} }
/** /**
...@@ -312,22 +315,23 @@ class SimpleCollection extends StudipArrayObject ...@@ -312,22 +315,23 @@ class SimpleCollection extends StudipArrayObject
if ($this->offsetExists($index)) { if ($this->offsetExists($index)) {
$this->deleted[] = $this->offsetGet($index); $this->deleted[] = $this->offsetGet($index);
} }
return parent::offsetUnset($index); parent::offsetUnset($index);
} }
/** /**
* sets the finder function * sets the finder function
* *
* @param Closure $finder * @param callable(): array<T> $finder
* @return void
*/ */
public function setFinder(Closure $finder) public function setFinder(callable $finder)
{ {
$this->finder = $finder; $this->finder = $finder;
} }
/** /**
* get deleted records collection * get deleted records collection
* @return SimpleCollection * @return SimpleCollection<T>
*/ */
public function getDeleted() public function getDeleted()
{ {
...@@ -338,7 +342,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -338,7 +342,7 @@ class SimpleCollection extends StudipArrayObject
* reloads the elements of the collection * reloads the elements of the collection
* by calling the finder function * by calling the finder function
* *
* @return number of records after refresh * @return ?int of records after refresh
*/ */
public function refresh() public function refresh()
{ {
...@@ -370,9 +374,9 @@ class SimpleCollection extends StudipArrayObject ...@@ -370,9 +374,9 @@ class SimpleCollection extends StudipArrayObject
* ~= regex * ~= regex
* *
* @param string $key the column name * @param string $key the column name
* @param mixed $value value to search for * @param mixed $values value to search for
* @param mixed $op operator to find * @param string|callable $op operator to find
* @return SimpleCollection with found records * @return SimpleCollection<T> with found records
*/ */
public function findBy($key, $values, $op = '==') public function findBy($key, $values, $op = '==')
{ {
...@@ -388,9 +392,9 @@ class SimpleCollection extends StudipArrayObject ...@@ -388,9 +392,9 @@ class SimpleCollection extends StudipArrayObject
* pass array for multiple values * pass array for multiple values
* *
* @param string $key the column name * @param string $key the column name
* @param mixed $value value to search for, * @param mixed $values value to search for,
* @param mixed $op operator to find * @param string|callable $op operator to find
* @return SimpleORMap found record * @return ?T found record
*/ */
public function findOneBy($key, $values, $op = '==') public function findOneBy($key, $values, $op = '==')
{ {
...@@ -404,10 +408,10 @@ class SimpleCollection extends StudipArrayObject ...@@ -404,10 +408,10 @@ class SimpleCollection extends StudipArrayObject
* apply given callback to all elements of * apply given callback to all elements of
* collection * collection
* *
* @param Closure $func the function to call * @param callable(T): int $func the function to call
* @return int addition of return values * @return int|false addition of return values
*/ */
public function each(Closure $func) public function each(callable $func)
{ {
$result = false; $result = false;
foreach ($this->storage as $record) { foreach ($this->storage as $record) {
...@@ -420,10 +424,10 @@ class SimpleCollection extends StudipArrayObject ...@@ -420,10 +424,10 @@ class SimpleCollection extends StudipArrayObject
* apply given callback to all elements of * apply given callback to all elements of
* collection and give back array of return values * collection and give back array of return values
* *
* @param Closure $func the function to call * @param callable(T, mixed): mixed $func the function to call
* @return array * @return array<mixed>
*/ */
public function map(Closure $func) public function map(callable $func)
{ {
$results = []; $results = [];
foreach ($this->storage as $key => $value) { foreach ($this->storage as $key => $value) {
...@@ -436,11 +440,11 @@ class SimpleCollection extends StudipArrayObject ...@@ -436,11 +440,11 @@ class SimpleCollection extends StudipArrayObject
* filter elements * filter elements
* if given callback returns true * if given callback returns true
* *
* @param Closure $func the function to call * @param ?callable(T, mixed): bool $func the function to call
* @param integer $limit limit number of found records * @param ?integer $limit limit number of found records
* @return SimpleCollection containing filtered elements * @return SimpleCollection<T> containing filtered elements
*/ */
public function filter(Closure $func = null, $limit = null) public function filter(callable $func = null, $limit = null)
{ {
$results = []; $results = [];
$found = 0; $found = 0;
...@@ -459,10 +463,10 @@ class SimpleCollection extends StudipArrayObject ...@@ -459,10 +463,10 @@ class SimpleCollection extends StudipArrayObject
* Returns whether any element of the collection returns true for the * Returns whether any element of the collection returns true for the
* given callback. * given callback.
* *
* @param Closure $func the function to call * @param callable(T, mixed): bool $func the function to call
* @return bool * @return bool
*/ */
public function any(Closure $func) public function any(callable $func)
{ {
foreach ($this->storage as $key => $value) { foreach ($this->storage as $key => $value) {
if (call_user_func($func, $value, $key)) { if (call_user_func($func, $value, $key)) {
...@@ -476,10 +480,10 @@ class SimpleCollection extends StudipArrayObject ...@@ -476,10 +480,10 @@ class SimpleCollection extends StudipArrayObject
* Returns whether every element of the collection returns true for the * Returns whether every element of the collection returns true for the
* given callback. * given callback.
* *
* @param Closure $func the function to call * @param callable(T, mixed): bool $func the function to call
* @return bool * @return bool
*/ */
public function every(Closure $func) public function every(callable $func)
{ {
foreach ($this->storage as $key => $value) { foreach ($this->storage as $key => $value) {
if (!call_user_func($func, $value, $key)) { if (!call_user_func($func, $value, $key)) {
...@@ -521,11 +525,11 @@ class SimpleCollection extends StudipArrayObject ...@@ -521,11 +525,11 @@ class SimpleCollection extends StudipArrayObject
* entry is returned, suitable for grouping by unique column * entry is returned, suitable for grouping by unique column
* *
* @param string $group_by the column to group by, pk if ommitted * @param string $group_by the column to group by, pk if ommitted
* @param mixed $only_these_fields limit returned fields * @param string|array|null $only_these_fields limit returned fields
* @param Closure $group_func closure to aggregate grouped entries * @param ?callable $group_func closure to aggregate grouped entries
* @return array assoc array * @return array assoc array
*/ */
public function toGroupedArray($group_by = 'id', $only_these_fields = null, Closure $group_func = null) public function toGroupedArray($group_by = 'id', $only_these_fields = null, callable $group_func = null)
{ {
$result = []; $result = [];
if (is_string($only_these_fields)) { if (is_string($only_these_fields)) {
...@@ -549,7 +553,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -549,7 +553,7 @@ class SimpleCollection extends StudipArrayObject
/** /**
* get the first element * get the first element
* *
* @return Array first element or null * @return ?T first element or null
*/ */
public function first() public function first()
{ {
...@@ -561,7 +565,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -561,7 +565,7 @@ class SimpleCollection extends StudipArrayObject
/** /**
* get the last element * get the last element
* *
* @return Array last element or null * @return ?T last element or null
*/ */
public function last() public function last()
{ {
...@@ -573,6 +577,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -573,6 +577,7 @@ class SimpleCollection extends StudipArrayObject
/** /**
* get the the value from given key from first element * get the the value from given key from first element
* *
* @param string $key
* @return mixed * @return mixed
*/ */
public function val($key) public function val($key)
...@@ -604,8 +609,8 @@ class SimpleCollection extends StudipArrayObject ...@@ -604,8 +609,8 @@ class SimpleCollection extends StudipArrayObject
* *
* @param string $key * @param string $key
* @param mixed $values * @param mixed $values
* @param mixed $op operator to find elements * @param string|callable(mixed, mixed|array): bool $op operator to find elements
* @return number of unsetted elements * @return int|false number of unsetted elements
*/ */
public function unsetBy($key, $values, $op = '==') public function unsetBy($key, $values, $op = '==')
{ {
...@@ -642,7 +647,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -642,7 +647,7 @@ class SimpleCollection extends StudipArrayObject
* *
* @param string $order columns to order by * @param string $order columns to order by
* @param integer $sort_flags * @param integer $sort_flags
* @return SimpleCollection the sorted collection * @return $this the sorted collection
*/ */
public function orderBy($order, $sort_flags = SORT_LOCALE_STRING) public function orderBy($order, $sort_flags = SORT_LOCALE_STRING)
{ {
...@@ -707,8 +712,8 @@ class SimpleCollection extends StudipArrayObject ...@@ -707,8 +712,8 @@ class SimpleCollection extends StudipArrayObject
* number of elements * number of elements
* *
* @param integer $arg1 * @param integer $arg1
* @param integer $arg2 * @param ?integer $arg2
* @return SimpleCollection * @return SimpleCollection<T>
*/ */
public function limit($arg1, $arg2 = null) public function limit($arg1, $arg2 = null)
{ {
...@@ -730,7 +735,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -730,7 +735,7 @@ class SimpleCollection extends StudipArrayObject
/** /**
* calls the given method on all elements * calls the given method on all elements
* of the collection * of the collection
* @param string $method methodname to call * @param literal-string $method methodname to call
* @param array $params parameters for methodcall * @param array $params parameters for methodcall
* @return array of all return values * @return array of all return values
*/ */
...@@ -747,7 +752,7 @@ class SimpleCollection extends StudipArrayObject ...@@ -747,7 +752,7 @@ class SimpleCollection extends StudipArrayObject
* calls undefineds methods on all elements of the collection * calls undefineds methods on all elements of the collection
* But beware of the dark side... * But beware of the dark side...
* *
* @param string $method methodname to call * @param literal-string $method methodname to call
* @param array $params parameters for methodcall * @param array $params parameters for methodcall
* @return array of all return values * @return array of all return values
*/ */
...@@ -759,7 +764,8 @@ class SimpleCollection extends StudipArrayObject ...@@ -759,7 +764,8 @@ class SimpleCollection extends StudipArrayObject
/** /**
* merge in another collection, elements are appended * merge in another collection, elements are appended
* *
* @param SimpleCollection $a_collection * @param SimpleCollection<T> $a_collection
* @return void
*/ */
public function merge(SimpleCollection $a_collection) public function merge(SimpleCollection $a_collection)
{ {
......
lib/models/SimpleORMap.class.php
+ 117
− 64
View file @ d62f1b74
This diff is collapsed.
lib/models/SimpleORMapCollection.class.php
+ 31
− 16
View file @ d62f1b74
...@@ -12,17 +12,25 @@ ...@@ -12,17 +12,25 @@
* @copyright 2012 Stud.IP Core-Group * @copyright 2012 Stud.IP Core-Group
* @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2 * @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
* @category Stud.IP * @category Stud.IP
*/ *
* @extends SimpleCollection<SimpleORMap>
*/
class SimpleORMapCollection extends SimpleCollection class SimpleORMapCollection extends SimpleCollection
{ {
/**
* @var int Exception error code denoting a wrong type of objects.
*/
const WRONG_OBJECT_TYPE = 1; const WRONG_OBJECT_TYPE = 1;
/**
* @var int Exception error code denoting that an object of this `id` already exists.
*/
const OBJECT_EXISTS = 2; const OBJECT_EXISTS = 2;
/** /**
* the record object this collection belongs to * the record object this collection belongs to
* *
* @var SimpleORMap * @var ?SimpleORMap
*/ */
protected $related_record; protected $related_record;
...@@ -37,11 +45,11 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -37,11 +45,11 @@ class SimpleORMapCollection extends SimpleCollection
* all objects should be of the same type * all objects should be of the same type
* *
* @throws InvalidArgumentException if first entry is not SimpleOrMap * @throws InvalidArgumentException if first entry is not SimpleOrMap
* @param array $data array with SimpleORMap objects * @param array<?SimpleORMap> $data array with SimpleORMap objects
* @param bool $strict check every element for correct type and unique pk * @param bool $strict check every element for correct type and unique pk
* @return SimpleORMapCollection * @return SimpleORMapCollection
*/ */
public static function createFromArray(Array $data, $strict = true) public static function createFromArray(array $data, $strict = true)
{ {
$ret = new SimpleORMapCollection(); $ret = new SimpleORMapCollection();
if (count($data)) { if (count($data)) {
...@@ -65,11 +73,11 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -65,11 +73,11 @@ class SimpleORMapCollection extends SimpleCollection
/** /**
* Constructor * Constructor
* *
* @param Closure $finder callable to fill collection * @param ?Closure $finder callable to fill collection
* @param array $options relationship options * @param ?array $options relationship options
* @param SimpleORMap $record related record * @param ?SimpleORMap $record related record
*/ */
public function __construct(Closure $finder = null, Array $options = null, SimpleORMap $record = null) public function __construct(Closure $finder = null, array $options = null, SimpleORMap $record = null)
{ {
$this->relation_options = $options; $this->relation_options = $options;
$this->related_record = $record; $this->related_record = $record;
...@@ -101,12 +109,13 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -101,12 +109,13 @@ class SimpleORMapCollection extends SimpleCollection
throw new InvalidArgumentException('Element could not be appended, element with id: ' . $exists->id . ' is in the way', self::OBJECT_EXISTS); throw new InvalidArgumentException('Element could not be appended, element with id: ' . $exists->id . ' is in the way', self::OBJECT_EXISTS);
} }
} }
return parent::offsetSet($index, $newval); parent::offsetSet($index, $newval);
} }
/** /**
* sets the allowed class name * sets the allowed class name
* @param string $class_name * @param class-string $class_name
* @return void
*/ */
public function setClassName($class_name) public function setClassName($class_name)
{ {
...@@ -118,6 +127,7 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -118,6 +127,7 @@ class SimpleORMapCollection extends SimpleCollection
* sets the related record * sets the related record
* *
* @param SimpleORMap $record * @param SimpleORMap $record
* @return void
*/ */
public function setRelatedRecord(SimpleORMap $record) public function setRelatedRecord(SimpleORMap $record)
{ {
...@@ -160,7 +170,7 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -160,7 +170,7 @@ class SimpleORMapCollection extends SimpleCollection
* returns element with given primary key value * returns element with given primary key value
* *
* @param string $value primary key value to search for * @param string $value primary key value to search for
* @return SimpleORMap * @return ?SimpleORMap
*/ */
public function find($value) public function find($value)
{ {
...@@ -177,10 +187,10 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -177,10 +187,10 @@ class SimpleORMapCollection extends SimpleCollection
* *
* @param string $group_by the column to group by, pk if ommitted * @param string $group_by the column to group by, pk if ommitted
* @param mixed $only_these_fields limit returned fields * @param mixed $only_these_fields limit returned fields
* @param Closure $group_func closure to aggregate grouped entries * @param ?callable $group_func closure to aggregate grouped entries
* @return array assoc array * @return array assoc array
*/ */
public function toGroupedArray($group_by = 'id', $only_these_fields = null, Closure $group_func = null) public function toGroupedArray($group_by = 'id', $only_these_fields = null, callable $group_func = null)
{ {
$result = []; $result = [];
foreach ($this as $record) { foreach ($this as $record) {
...@@ -202,7 +212,7 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -202,7 +212,7 @@ class SimpleORMapCollection extends SimpleCollection
* internal deleted collection * internal deleted collection
* *
* @param string $id primary key of element * @param string $id primary key of element
* @return number of unsetted elements * @return number of unsetted elements
*/ */
public function unsetByPk($id) public function unsetByPk($id)
{ {
...@@ -216,12 +226,17 @@ class SimpleORMapCollection extends SimpleCollection ...@@ -216,12 +226,17 @@ class SimpleORMapCollection extends SimpleCollection
* *
* @param SimpleORMapCollection $a_collection * @param SimpleORMapCollection $a_collection
* @param string $mode 'replace' or 'ignore' * @param string $mode 'replace' or 'ignore'
* @return void
*/ */
public function merge(SimpleCollection $a_collection) public function merge(SimpleCollection $a_collection, string $mode = 'ignore')
{ {
$mode = func_get_arg(1); $mode = func_get_arg(1);
foreach ($a_collection as $element) { foreach ($a_collection as $element) {
try { try {
/**
* @throws InvalidArgumentException
* @see SimpleORMapCollection::offsetSet()
*/
$this[] = $element; $this[] = $element;
} catch (InvalidArgumentException $e) { } catch (InvalidArgumentException $e) {
if ($e->getCode() === self::OBJECT_EXISTS) { if ($e->getCode() === self::OBJECT_EXISTS) {
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment