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
* Quotes the given value in a form appropriate for the type.
* If no explicit type is given, the value's PHP type is used.
*
* @param mixed PHP value to quote
* @param int parameter type (e.g. PDO::PARAM_STR)
* @return string quoted SQL string
* @param mixed $value PHP value to quote
* @param ?int $type parameter type (e.g. PDO::PARAM_STR)
* @return string quoted SQL string
*/
public function quote($value, $type = NULL)
public function quote($value, $type = null)
{
if (!isset($type)) {
if (is_null($value)) {
......
lib/models/SimpleCollection.class.php
+ 59
− 53
View file @ d62f1b74
......@@ -19,13 +19,15 @@ if (!defined('SORT_FLAG_CASE')) {
* @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 Closure
* @var ?callable(): array<T>
*/
protected $finder;
......@@ -38,7 +40,7 @@ class SimpleCollection extends StudipArrayObject
/**
* collection with deleted records
* @var SimpleCollection
* @var static
*/
protected $deleted;
......@@ -46,10 +48,10 @@ class SimpleCollection extends StudipArrayObject
* creates a collection from an array of arrays
* all arrays should contain same keys, but is not enforced
*
* @param array $data array containing assoc arrays
* @return SimpleCollection
* @param array<T> $data array containing assoc arrays
* @return SimpleCollection<T>
*/
public static function createFromArray(Array $data)
public static function createFromArray(array $data)
{
return new self($data);
}
......@@ -59,7 +61,7 @@ class SimpleCollection extends StudipArrayObject
* if ArrayAccess interface is not available
*
* @param mixed $a
* @return ArrayAccess
* @return StudipArrayObject|ArrayAccess
*/
public static function arrayToArrayObject($a)
{
......@@ -83,14 +85,14 @@ class SimpleCollection extends StudipArrayObject
* returns closure to compare a value against given arguments
* using given operator
*
* @param string $operator
* @param mixed $args
* @param string|callable(mixed, mixed|array): bool $operator
* @param mixed|array $args
* @throws InvalidArgumentException
* @return Closure comparison function
* @return callable(mixed): bool comparison function
*/
public static function getCompFunc($operator, $args)
{
if ($operator instanceOf Closure) {
if (is_callable($operator)) {
$comp_func = function ($a) use ($args, $operator) {
return $operator($a, $args);
};
......@@ -234,14 +236,14 @@ class SimpleCollection extends StudipArrayObject
/**
* 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 = [])
{
parent::__construct();
$this->finder = $data instanceof Closure ? $data : null;
$this->finder = is_callable($data) ? $data : null;
$this->deleted = clone $this;
if ($data instanceof Closure) {
if (is_callable($data)) {
$this->refresh();
} else {
$this->exchangeArray($data);
......@@ -283,7 +285,7 @@ class SimpleCollection extends StudipArrayObject
*/
public function append($newval)
{
return parent::append(static::arrayToArrayObject($newval));
parent::append(static::arrayToArrayObject($newval));
}
/**
......@@ -291,13 +293,14 @@ class SimpleCollection extends StudipArrayObject
* ensures the value has ArrayAccess
*
* @see ArrayObject::offsetSet()
* @return void
*/
public function offsetSet($index, $newval)
{
if (is_numeric($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
if ($this->offsetExists($index)) {
$this->deleted[] = $this->offsetGet($index);
}
return parent::offsetUnset($index);
parent::offsetUnset($index);
}
/**
* 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;
}
/**
* get deleted records collection
* @return SimpleCollection
* @return SimpleCollection<T>
*/
public function getDeleted()
{
......@@ -338,7 +342,7 @@ class SimpleCollection extends StudipArrayObject
* reloads the elements of the collection
* by calling the finder function
*
* @return number of records after refresh
* @return ?int of records after refresh
*/
public function refresh()
{
......@@ -370,9 +374,9 @@ class SimpleCollection extends StudipArrayObject
* ~= regex
*
* @param string $key the column name
* @param mixed $value value to search for
* @param mixed $op operator to find
* @return SimpleCollection with found records
* @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 = '==')
{
......@@ -388,9 +392,9 @@ class SimpleCollection extends StudipArrayObject
* pass array for multiple values
*
* @param string $key the column name
* @param mixed $value value to search for,
* @param mixed $op operator to find
* @return SimpleORMap found record
* @param mixed $values value to search for,
* @param string|callable $op operator to find
* @return ?T found record
*/
public function findOneBy($key, $values, $op = '==')
{
......@@ -404,10 +408,10 @@ class SimpleCollection extends StudipArrayObject
* apply given callback to all elements of
* collection
*
* @param Closure $func the function to call
* @return int addition of return values
* @param callable(T): int $func the function to call
* @return int|false addition of return values
*/
public function each(Closure $func)
public function each(callable $func)
{
$result = false;
foreach ($this->storage as $record) {
......@@ -420,10 +424,10 @@ class SimpleCollection extends StudipArrayObject
* apply given callback to all elements of
* collection and give back array of return values
*
* @param Closure $func the function to call
* @return array
* @param callable(T, mixed): mixed $func the function to call
* @return array<mixed>
*/
public function map(Closure $func)
public function map(callable $func)
{
$results = [];
foreach ($this->storage as $key => $value) {
......@@ -436,11 +440,11 @@ class SimpleCollection extends StudipArrayObject
* filter elements
* if given callback returns true
*
* @param Closure $func the function to call
* @param integer $limit limit number of found records
* @return SimpleCollection containing filtered elements
* @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(Closure $func = null, $limit = null)
public function filter(callable $func = null, $limit = null)
{
$results = [];
$found = 0;
......@@ -459,10 +463,10 @@ class SimpleCollection extends StudipArrayObject
* Returns whether any element of the collection returns true for the
* given callback.
*
* @param Closure $func the function to call
* @param callable(T, mixed): bool $func the function to call
* @return bool
*/
public function any(Closure $func)
public function any(callable $func)
{
foreach ($this->storage as $key => $value) {
if (call_user_func($func, $value, $key)) {
......@@ -476,10 +480,10 @@ class SimpleCollection extends StudipArrayObject
* Returns whether every element of the collection returns true for the
* given callback.
*
* @param Closure $func the function to call
* @param callable(T, mixed): bool $func the function to call
* @return bool
*/
public function every(Closure $func)
public function every(callable $func)
{
foreach ($this->storage as $key => $value) {
if (!call_user_func($func, $value, $key)) {
......@@ -521,11 +525,11 @@ class SimpleCollection extends StudipArrayObject
* 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 Closure $group_func closure to aggregate grouped entries
* @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, Closure $group_func = null)
public function toGroupedArray($group_by = 'id', $only_these_fields = null, callable $group_func = null)
{
$result = [];
if (is_string($only_these_fields)) {
......@@ -549,7 +553,7 @@ class SimpleCollection extends StudipArrayObject
/**
* get the first element
*
* @return Array first element or null
* @return ?T first element or null
*/
public function first()
{
......@@ -561,7 +565,7 @@ class SimpleCollection extends StudipArrayObject
/**
* get the last element
*
* @return Array last element or null
* @return ?T last element or null
*/
public function last()
{
......@@ -573,6 +577,7 @@ class SimpleCollection extends StudipArrayObject
/**
* get the the value from given key from first element
*
* @param string $key
* @return mixed
*/
public function val($key)
......@@ -604,8 +609,8 @@ class SimpleCollection extends StudipArrayObject
*
* @param string $key
* @param mixed $values
* @param mixed $op operator to find elements
* @return number of unsetted elements
* @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 = '==')
{
......@@ -642,7 +647,7 @@ class SimpleCollection extends StudipArrayObject
*
* @param string $order columns to order by
* @param integer $sort_flags
* @return SimpleCollection the sorted collection
* @return $this the sorted collection
*/
public function orderBy($order, $sort_flags = SORT_LOCALE_STRING)
{
......@@ -707,8 +712,8 @@ class SimpleCollection extends StudipArrayObject
* number of elements
*
* @param integer $arg1
* @param integer $arg2
* @return SimpleCollection
* @param ?integer $arg2
* @return SimpleCollection<T>
*/
public function limit($arg1, $arg2 = null)
{
......@@ -730,7 +735,7 @@ class SimpleCollection extends StudipArrayObject
/**
* calls the given method on all elements
* of the collection
* @param string $method methodname to call
* @param literal-string $method methodname to call
* @param array $params parameters for methodcall
* @return array of all return values
*/
......@@ -747,7 +752,7 @@ class SimpleCollection extends StudipArrayObject
* calls undefineds methods on all elements of the collection
* 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
* @return array of all return values
*/
......@@ -759,7 +764,8 @@ class SimpleCollection extends StudipArrayObject
/**
* merge in another collection, elements are appended
*
* @param SimpleCollection $a_collection
* @param SimpleCollection<T> $a_collection
* @return void
*/
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 @@
* @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>
*/
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
* @var ?SimpleORMap
*/
protected $related_record;
......@@ -37,11 +45,11 @@ class SimpleORMapCollection extends SimpleCollection
* all objects should be of the same type
*
* @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
* @return SimpleORMapCollection
*/
public static function createFromArray(Array $data, $strict = true)
public static function createFromArray(array $data, $strict = true)
{
$ret = new SimpleORMapCollection();
if (count($data)) {
......@@ -65,11 +73,11 @@ class SimpleORMapCollection extends SimpleCollection
/**
* Constructor
*
* @param Closure $finder callable to fill collection
* @param array $options relationship options
* @param SimpleORMap $record related record
* @param ?Closure $finder callable to fill collection
* @param ?array $options relationship options
* @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->related_record = $record;
......@@ -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);
}
}
return parent::offsetSet($index, $newval);
parent::offsetSet($index, $newval);
}
/**
* sets the allowed class name
* @param string $class_name
* @param class-string $class_name
* @return void
*/
public function setClassName($class_name)
{
......@@ -118,6 +127,7 @@ class SimpleORMapCollection extends SimpleCollection
* sets the related record
*
* @param SimpleORMap $record
* @return void
*/
public function setRelatedRecord(SimpleORMap $record)
{
......@@ -160,7 +170,7 @@ class SimpleORMapCollection extends SimpleCollection
* returns element with given primary key value
*
* @param string $value primary key value to search for
* @return SimpleORMap
* @return ?SimpleORMap
*/
public function find($value)
{
......@@ -177,10 +187,10 @@ class SimpleORMapCollection extends SimpleCollection
*
* @param string $group_by the column to group by, pk if ommitted
* @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
*/
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 = [];
foreach ($this as $record) {
......@@ -202,7 +212,7 @@ class SimpleORMapCollection extends SimpleCollection
* internal deleted collection
*
* @param string $id primary key of element
* @return number of unsetted elements
* @return number of unsetted elements
*/
public function unsetByPk($id)
{
......@@ -216,12 +226,17 @@ class SimpleORMapCollection extends SimpleCollection
*
* @param SimpleORMapCollection $a_collection
* @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);
foreach ($a_collection as $element) {
try {
/**
* @throws InvalidArgumentException
* @see SimpleORMapCollection::offsetSet()
*/
$this[] = $element;
} catch (InvalidArgumentException $e) {
if ($e->getCode() === self::OBJECT_EXISTS) {
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment