From ee3ea44a81fde863ff58581e20c837a2a8e41dd8 Mon Sep 17 00:00:00 2001 From: Kregs Date: Thu, 9 Jan 2025 22:54:48 +0100 Subject: [PATCH] add phpdoc --- src/Collection.php | 105 ++++++++++++++++++++++++++++++++++++++++++++- src/Connection.php | 68 +++++++++++++++++++++++++++-- src/Expression.php | 61 ++++++++++++++++++++++---- src/Model.php | 82 +++++++++++++++++++++++++++++++++-- src/Query.php | 30 ++++++++++++- 5 files changed, 329 insertions(+), 17 deletions(-) diff --git a/src/Collection.php b/src/Collection.php index ad7b26f..b23905d 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -12,33 +12,64 @@ class Collection implements IteratorAggregate, Countable, JsonSerializable { private array $elements; + /** + * Constructor + * + * @param array $elements + */ public function __construct(array $elements = []) { $this->elements = $elements; } + /** + * Return first element of the collection + * + * @return mixed + */ public function first(): mixed { return reset($this->elements); } + /** + * Return last element of the collection + * + * @return mixed + */ public function last(): mixed { return end($this->elements); } + /** + * Return collection length + * + * @return integer + */ public function count(): int { return count($this->elements); } + /** + * Clear all elements in collection + * + * @return boolean + */ public function clear(): bool { $this->elements = []; return count($this->elements) == 0; } - public function index($index): mixed + /** + * Return element in nth position in the collection + * + * @param int $index + * @return mixed + */ + public function index(int $index): mixed { if (isset($this->elements[$index])) { return $this->elements[$index]; @@ -46,31 +77,67 @@ class Collection implements IteratorAggregate, Countable, JsonSerializable return null; } + /** + * Return random element of the collection + * + * @return mixed + */ public function random(): mixed { return array_rand($this->elements); } + /** + * Reduce function on the collection + * + * @param callable $fn + * @param mixed $initial + * @return mixed + */ public function reduce(callable $fn, mixed $initial): mixed { return array_reduce($this->elements, $fn, $initial); } + /** + * Map function on the collection + * + * @param callable $fn + * @return Collection + */ public function map(callable $fn): Collection { return new Collection(array_map($fn, $this->elements)); } + /** + * Apply callable function on each element of the function + * + * @param callable $fn + * @return void + */ public function each(callable $fn): void { array_walk($this->elements, $fn); } + /** + * Apply function to filter collection + * + * @param callable $fn + * @return Collection + */ public function filter(callable $fn): Collection { return new Collection(array_filter($this->elements, $fn, ARRAY_FILTER_USE_BOTH)); } + /** + * Return collection of the key related items in current collection + * + * @param string $key + * @return Collection + */ public function pluck(string $key): Collection { return new Collection(array_map(function ($item) use ($key) { @@ -83,36 +150,72 @@ class Collection implements IteratorAggregate, Countable, JsonSerializable }, $this->elements)); } + /** + * Return actual collection items in an array + * + * @return array + */ public function toArray(): array { return $this->elements; } + /** + * Return if the collection are empty + * + * @return boolean + */ public function empty(): bool { return empty($this->elements); } + /** + * Add an element to the collection + * + * @param mixed $element + * @return void + */ public function add(mixed $element): void { $this->elements[] = $element; } + /** + * Return all values of the collection + * + * @return array + */ public function values(): array { return array_values($this->elements); } + /** + * Return all items of the collection + * + * @return array + */ public function items(): array { return $this->elements; } + /** + * Iterator + * + * @return Traversable + */ public function getIterator(): Traversable { return new ArrayIterator($this->elements); } + /** + * Return json serialization of the collection + * + * @return mixed + */ public function jsonSerialize(): mixed { return $this->elements; diff --git a/src/Connection.php b/src/Connection.php index ee4c382..68d1452 100644 --- a/src/Connection.php +++ b/src/Connection.php @@ -137,12 +137,25 @@ class Connection }; } + /** + * Execute raw query on the current pdo connection + * + * @param string $rawquery + * @return boolean + */ public function executeRawQuery(string $rawquery): bool { $stmt = $this->pdo->prepare($rawquery); return $stmt->execute(); } + /** + * Run prepared query in the current pdo connection + * + * @param Query $query + * @param $fetchmode + * @return mixed + */ public function getSelectQuery(Query $query, $fetchmode = PDO::FETCH_ASSOC): mixed { $stmt = $this->pdo->prepare($query->getQuery()); @@ -152,6 +165,12 @@ class Connection return $stmt->fetchAll($fetchmode); } + /** + * Run prepared update query on the current pdo connection + * + * @param Query $query + * @return boolean + */ public function updateQuery(Query $query): bool { $stmt = $this->pdo->prepare($query->getQuery()); @@ -160,6 +179,12 @@ class Connection return $stmt->execute(); } + /** + * Run prepared insert query on the current pdo connection + * + * @param Query $query + * @return mixed + */ public function insertQuery(Query $query): mixed { $stmt = $this->pdo->prepare($query->getQuery()); @@ -173,6 +198,11 @@ class Connection } } + /** + * Begin transaction on the current pdo connection + * + * @return boolean + */ public function beginTransaction(): bool { if ($this->pdo) { @@ -181,6 +211,11 @@ class Connection return false; } + /** + * Commit transaction on the current pdo connection + * + * @return boolean + */ public function commit(): bool { if ($this->pdo) { @@ -189,6 +224,11 @@ class Connection return false; } + /** + * Rollback transaction on the current pdo connection + * + * @return boolean + */ public function rollback(): bool { if ($this->pdo) { @@ -197,6 +237,13 @@ class Connection return false; } + /** + * Init the connections + * + * @param [type] $config + * @param array $connections + * @return void + */ public static function init($config, array $connections = ["default"]) { self::fillInstances($config, $connections); @@ -226,17 +273,32 @@ class Connection throw new \Exception("Unknown connection"); } - public function getError() + /** + * Return last error + * + * @return string + */ + public function getError(): string { return $this->error; } - public function getPdo() + /** + * Return current PDO object + * + * @return PDO + */ + public function getPdo(): PDO { return $this->pdo; } - public function getDriverType() + /** + * Return current database driver type currently used + * + * @return string + */ + public function getDriverType(): string { return $this->type; } diff --git a/src/Expression.php b/src/Expression.php index 27d451e..4cf5ba3 100644 --- a/src/Expression.php +++ b/src/Expression.php @@ -4,9 +4,9 @@ namespace Kletellier\PdoWrapper; class Expression { - private $condition; - private $operator; - private $value; + private string $condition; + private string $operator; + private mixed $value; public function __construct($condition, $operator, $value) { @@ -15,6 +15,11 @@ class Expression $this->value = $value; } + /** + * Return raw value of the expression + * + * @return string + */ public function raw(): string { $operator = trim(strtolower($this->operator)); @@ -34,40 +39,78 @@ class Expression return "(" . $this->condition . " " . $this->operator . " ? )"; } + /** + * Return if the condition need to evaluate data + * + * @return boolean + */ public function hasData() { $operator = trim(strtolower($this->operator)); return (in_array($operator, ["isnull","notnull"])) ? false : true; } - public function getCondition() + /** + * Return actual condition + * + * @return string + */ + public function getCondition(): string { return $this->condition; } - public function setCondition($condition) + /** + * Set condition + * + * @param string $condition + * @return self + */ + public function setCondition(string $condition): self { $this->condition = $condition; return $this; } - public function getOperator() + /** + * Get actual operator + * + * @return string + */ + public function getOperator(): string { return $this->operator; } - public function setOperator($operator) + /** + * Set operator + * + * @param string $operator + * @return self + */ + public function setOperator(string $operator): self { $this->operator = $operator; return $this; } - public function getValue() + /** + * Get the value of the expression + * + * @return mixed + */ + public function getValue(): mixed { return $this->value; } - public function setValue($value) + /** + * Set the value of the expression + * + * @param mixed $value + * @return void + */ + public function setValue(mixed $value) { $this->value = $value; return $this; diff --git a/src/Model.php b/src/Model.php index 4de99b3..78947dc 100644 --- a/src/Model.php +++ b/src/Model.php @@ -14,6 +14,11 @@ class Model implements JsonSerializable private bool $new; private bool $ro; + /** + * Constructor + * + * @param boolean $ro readonly model + */ public function __construct($ro = false) { $this->new = true; @@ -36,44 +41,88 @@ class Model implements JsonSerializable } } + /** + * Return table + * + * @return string + */ public function getTable(): string { return $this->table; } + /** + * Define table + * + * @param string $table + * @return self + */ public function setTable(string $table): self { $this->table = $table; return $this; } + /** + * Return current key value attributes + * + * @return array + */ public function getValues(): array { return $this->values; } + /** + * Return current primary key + * + * @return string + */ public function getPk(): string { return $this->pk; } + /** + * Set primary key + * + * @param string $pk + * @return self + */ public function setPk(string $pk): self { $this->pk = $pk; return $this; } - public function getConnection() + /** + * Return actual connection + * + * @return string + */ + public function getConnection(): string { return $this->connection; } - public function setConnection($connection) + /** + * Set connection + * + * @param string $connection + * @return void + */ + public function setConnection(string $connection) { $this->connection = $connection; return $this; } + /** + * Fill values from key value array + * + * @param mixed $data + * @return self + */ public function fillData(mixed $data): self { $this->values = $data; @@ -82,6 +131,12 @@ class Model implements JsonSerializable return $this; } + /** + * Find specific element in the table on the primary key + * + * @param mixed $key + * @return mixed + */ public function find(mixed $key): mixed { $qb = $this->newQueryBuilder(get_class($this)); @@ -93,6 +148,11 @@ class Model implements JsonSerializable return null; } + /** + * Save current model + * + * @return boolean + */ public function save(): bool { $ret = false; @@ -126,7 +186,13 @@ class Model implements JsonSerializable return $ret; } - public function newQueryBuilder($className): QueryBuilder + /** + * Return new QueryBuilder on the model + * + * @param string $className + * @return QueryBuilder + */ + public function newQueryBuilder(string $className): QueryBuilder { return new QueryBuilder($this->table, $this->pk, $this->connection, $className); } @@ -153,6 +219,11 @@ class Model implements JsonSerializable return static::class; } + /** + * Static method to return new QueryBuilder + * + * @return QueryBuilder + */ public static function q(): QueryBuilder { $cls = self::getClassName(); @@ -178,6 +249,11 @@ class Model implements JsonSerializable return $table; } + /** + * Serialize the model in Json + * + * @return mixed + */ public function jsonSerialize(): mixed { return $this->values; diff --git a/src/Query.php b/src/Query.php index a90b796..4ab6961 100644 --- a/src/Query.php +++ b/src/Query.php @@ -13,7 +13,13 @@ class Query $this->data = []; } - public function addData($value) + /** + * Add data to the query + * + * @param array|mixed $value + * @return void + */ + public function addData(mixed $value) { if (is_array($value)) { $this->data = array_merge($this->data, $value); @@ -22,22 +28,44 @@ class Query } } + /** + * Return statement + * + * @return string + */ public function getQuery(): string { return $this->query; } + /** + * Set Statement + * + * @param string $query + * @return void + */ public function setQuery(string $query) { $this->query = $query; return $this; } + /** + * Return current data of the query + * + * @return array + */ public function getData(): array { return $this->data; } + /** + * Set data of the query + * + * @param array $data + * @return void + */ public function setData(array $data) { $this->data = $data;