From 598b11c242bd8ca87b1518ba0390a508cb893643 Mon Sep 17 00:00:00 2001 From: "Jonathan H. Wage" Date: Thu, 30 May 2019 14:43:07 -0500 Subject: [PATCH] Add proper types to Doctrine\DBAL\Query namespace. --- .../Query/Expression/CompositeExpression.php | 26 ++- .../Query/Expression/ExpressionBuilder.php | 62 ++----- lib/Doctrine/DBAL/Query/QueryBuilder.php | 169 ++++++++---------- 3 files changed, 97 insertions(+), 160 deletions(-) diff --git a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php index 93600f0ffb4..c62bc4d19e2 100644 --- a/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php +++ b/lib/Doctrine/DBAL/Query/Expression/CompositeExpression.php @@ -41,7 +41,7 @@ class CompositeExpression implements Countable * @param string $type Instance type of composite expression. * @param self[]|string[] $parts Composition of expressions to be joined on composite expression. */ - public function __construct($type, array $parts = []) + public function __construct(string $type, array $parts = []) { $this->type = $type; @@ -51,11 +51,11 @@ public function __construct($type, array $parts = []) /** * Adds multiple parts to composite expression. * - * @param self[]|string[] $parts + * @param array $parts * - * @return \Doctrine\DBAL\Query\Expression\CompositeExpression + * @return $this */ - public function addMultiple(array $parts = []) + public function addMultiple(array $parts = []) : self { foreach ($parts as $part) { $this->add($part); @@ -67,11 +67,11 @@ public function addMultiple(array $parts = []) /** * Adds an expression to composite expression. * - * @param mixed $part + * @param self|string $part * - * @return \Doctrine\DBAL\Query\Expression\CompositeExpression + * @return $this */ - public function add($part) + public function add($part) : self { if (empty($part)) { return $this; @@ -88,20 +88,16 @@ public function add($part) /** * Retrieves the amount of expressions on composite expression. - * - * @return int */ - public function count() + public function count() : int { return count($this->parts); } /** * Retrieves the string representation of this composite expression. - * - * @return string */ - public function __toString() + public function __toString() : string { if ($this->count() === 1) { return (string) $this->parts[0]; @@ -112,10 +108,8 @@ public function __toString() /** * Returns the type of this composite expression (AND/OR). - * - * @return string */ - public function getType() + public function getType() : string { return $this->type; } diff --git a/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php b/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php index 573df7b60b0..8aac8662797 100644 --- a/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php +++ b/lib/Doctrine/DBAL/Query/Expression/ExpressionBuilder.php @@ -51,10 +51,8 @@ public function __construct(Connection $connection) * * @param mixed $x Optional clause. Defaults = null, but requires * at least one defined when converting to string. - * - * @return CompositeExpression */ - public function andX($x = null) + public function andX($x = null) : CompositeExpression { return new CompositeExpression(CompositeExpression::TYPE_AND, func_get_args()); } @@ -70,10 +68,8 @@ public function andX($x = null) * * @param mixed $x Optional clause. Defaults = null, but requires * at least one defined when converting to string. - * - * @return CompositeExpression */ - public function orX($x = null) + public function orX($x = null) : CompositeExpression { return new CompositeExpression(CompositeExpression::TYPE_OR, func_get_args()); } @@ -84,10 +80,8 @@ public function orX($x = null) * @param mixed $x The left expression. * @param string $operator One of the ExpressionBuilder::* constants. * @param mixed $y The right expression. - * - * @return string */ - public function comparison($x, $operator, $y) + public function comparison($x, string $operator, $y) : string { return $x . ' ' . $operator . ' ' . $y; } @@ -104,10 +98,8 @@ public function comparison($x, $operator, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function eq($x, $y) + public function eq($x, $y) : string { return $this->comparison($x, self::EQ, $y); } @@ -123,10 +115,8 @@ public function eq($x, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function neq($x, $y) + public function neq($x, $y) : string { return $this->comparison($x, self::NEQ, $y); } @@ -142,10 +132,8 @@ public function neq($x, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function lt($x, $y) + public function lt($x, $y) : string { return $this->comparison($x, self::LT, $y); } @@ -161,10 +149,8 @@ public function lt($x, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function lte($x, $y) + public function lte($x, $y) : string { return $this->comparison($x, self::LTE, $y); } @@ -180,10 +166,8 @@ public function lte($x, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function gt($x, $y) + public function gt($x, $y) : string { return $this->comparison($x, self::GT, $y); } @@ -199,10 +183,8 @@ public function gt($x, $y) * * @param mixed $x The left expression. * @param mixed $y The right expression. - * - * @return string */ - public function gte($x, $y) + public function gte($x, $y) : string { return $this->comparison($x, self::GTE, $y); } @@ -211,10 +193,8 @@ public function gte($x, $y) * Creates an IS NULL expression with the given arguments. * * @param string $x The field in string format to be restricted by IS NULL. - * - * @return string */ - public function isNull($x) + public function isNull(string $x) : string { return $x . ' IS NULL'; } @@ -223,10 +203,8 @@ public function isNull($x) * Creates an IS NOT NULL expression with the given arguments. * * @param string $x The field in string format to be restricted by IS NOT NULL. - * - * @return string */ - public function isNotNull($x) + public function isNotNull(string $x) : string { return $x . ' IS NOT NULL'; } @@ -236,10 +214,8 @@ public function isNotNull($x) * * @param string $x Field in string format to be inspected by LIKE() comparison. * @param mixed $y Argument to be used in LIKE() comparison. - * - * @return string */ - public function like($x, $y/*, ?string $escapeChar = null */) + public function like(string $x, $y/*, ?string $escapeChar = null */) : string { return $this->comparison($x, 'LIKE', $y) . (func_num_args() >= 3 ? sprintf(' ESCAPE %s', func_get_arg(2)) : ''); @@ -250,10 +226,8 @@ public function like($x, $y/*, ?string $escapeChar = null */) * * @param string $x Field in string format to be inspected by NOT LIKE() comparison. * @param mixed $y Argument to be used in NOT LIKE() comparison. - * - * @return string */ - public function notLike($x, $y/*, ?string $escapeChar = null */) + public function notLike(string $x, $y/*, ?string $escapeChar = null */) : string { return $this->comparison($x, 'NOT LIKE', $y) . (func_num_args() >= 3 ? sprintf(' ESCAPE %s', func_get_arg(2)) : ''); @@ -264,10 +238,8 @@ public function notLike($x, $y/*, ?string $escapeChar = null */) * * @param string $x The field in string format to be inspected by IN() comparison. * @param string|string[] $y The placeholder or the array of values to be used by IN() comparison. - * - * @return string */ - public function in($x, $y) + public function in(string $x, $y) : string { return $this->comparison($x, 'IN', '(' . implode(', ', (array) $y) . ')'); } @@ -277,10 +249,8 @@ public function in($x, $y) * * @param string $x The field in string format to be inspected by NOT IN() comparison. * @param string|string[] $y The placeholder or the array of values to be used by NOT IN() comparison. - * - * @return string */ - public function notIn($x, $y) + public function notIn(string $x, $y) : string { return $this->comparison($x, 'NOT IN', '(' . implode(', ', (array) $y) . ')'); } @@ -288,7 +258,7 @@ public function notIn($x, $y) /** * Creates an SQL literal expression from the string. */ - public function literal(string $input) + public function literal(string $input) : string { return $this->connection->quote($input); } diff --git a/lib/Doctrine/DBAL/Query/QueryBuilder.php b/lib/Doctrine/DBAL/Query/QueryBuilder.php index 9dd5c9d66cf..d1e6d31dab5 100644 --- a/lib/Doctrine/DBAL/Query/QueryBuilder.php +++ b/lib/Doctrine/DBAL/Query/QueryBuilder.php @@ -59,7 +59,7 @@ class QueryBuilder /** * The array of SQL parts collected. * - * @var mixed[] + * @var array */ private $sqlParts = [ 'select' => [], @@ -83,14 +83,14 @@ class QueryBuilder /** * The query parameters. * - * @var mixed[] + * @var array|array */ private $params = []; /** * The parameter type map of this query. * - * @var int[]|string[] + * @var array|array */ private $paramTypes = []; @@ -113,14 +113,14 @@ class QueryBuilder * * @var int */ - private $firstResult = null; + private $firstResult = 0; /** * The maximum number of results to retrieve. * - * @var int + * @var int|null */ - private $maxResults = null; + private $maxResults; /** * The counter of bound parameters used with {@see bindValue). @@ -152,30 +152,24 @@ public function __construct(Connection $connection) * * For more complex expression construction, consider storing the expression * builder object in a local variable. - * - * @return ExpressionBuilder */ - public function expr() + public function expr() : ExpressionBuilder { return $this->connection->getExpressionBuilder(); } /** * Gets the type of the currently built query. - * - * @return int */ - public function getType() + public function getType() : int { return $this->type; } /** * Gets the associated DBAL Connection for this query builder. - * - * @return Connection */ - public function getConnection() + public function getConnection() : Connection { return $this->connection; } @@ -185,7 +179,7 @@ public function getConnection() * * @return int Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN. */ - public function getState() + public function getState() : int { return $this->state; } @@ -219,7 +213,7 @@ public function execute() * * @return string The SQL query string. */ - public function getSQL() + public function getSQL() : string { if ($this->sql !== null && $this->state === self::STATE_CLEAN) { return $this->sql; @@ -266,7 +260,7 @@ public function getSQL() * * @return $this This QueryBuilder instance. */ - public function setParameter($key, $value, $type = null) + public function setParameter($key, $value, $type = null) : self { if ($type !== null) { $this->paramTypes[$key] = $type; @@ -291,12 +285,12 @@ public function setParameter($key, $value, $type = null) * )); * * - * @param mixed[] $params The query parameters to set. - * @param int[]|string[] $types The query parameters types to set. + * @param array|array $params The query parameters to set. + * @param array|array $types The query parameters types to set. * * @return $this This QueryBuilder instance. */ - public function setParameters(array $params, array $types = []) + public function setParameters(array $params, array $types = []) : self { $this->paramTypes = $types; $this->params = $params; @@ -307,9 +301,9 @@ public function setParameters(array $params, array $types = []) /** * Gets all defined query parameters for the query being constructed indexed by parameter index or name. * - * @return mixed[] The currently defined query parameters indexed by parameter index or name. + * @return array The currently defined query parameters indexed by parameter index or name. */ - public function getParameters() + public function getParameters() : array { return $this->params; } @@ -317,7 +311,7 @@ public function getParameters() /** * Gets a (previously set) query parameter of the query being constructed. * - * @param mixed $key The key (index or name) of the bound parameter. + * @param string|int $key The key (index or name) of the bound parameter. * * @return mixed The value of the bound parameter. */ @@ -329,9 +323,9 @@ public function getParameter($key) /** * Gets all defined query parameter types for the query being constructed indexed by parameter index or name. * - * @return int[]|string[] The currently defined query parameter types indexed by parameter index or name. + * @return array The currently defined query parameter types indexed by parameter index or name. */ - public function getParameterTypes() + public function getParameterTypes() : array { return $this->paramTypes; } @@ -339,7 +333,7 @@ public function getParameterTypes() /** * Gets a (previously set) query parameter type of the query being constructed. * - * @param mixed $key The key (index or name) of the bound parameter type. + * @param string|int $key The key (index or name) of the bound parameter type. * * @return mixed The value of the bound parameter type. */ @@ -355,7 +349,7 @@ public function getParameterType($key) * * @return $this This QueryBuilder instance. */ - public function setFirstResult($firstResult) + public function setFirstResult(int $firstResult) : self { $this->state = self::STATE_DIRTY; $this->firstResult = $firstResult; @@ -369,7 +363,7 @@ public function setFirstResult($firstResult) * * @return int The position of the first result. */ - public function getFirstResult() + public function getFirstResult() : int { return $this->firstResult; } @@ -381,7 +375,7 @@ public function getFirstResult() * * @return $this This QueryBuilder instance. */ - public function setMaxResults($maxResults) + public function setMaxResults(int $maxResults) : self { $this->state = self::STATE_DIRTY; $this->maxResults = $maxResults; @@ -395,7 +389,7 @@ public function setMaxResults($maxResults) * * @return int The maximum number of results. */ - public function getMaxResults() + public function getMaxResults() : int { return $this->maxResults; } @@ -406,13 +400,11 @@ public function getMaxResults() * The available parts are: 'select', 'from', 'set', 'where', * 'groupBy', 'having' and 'orderBy'. * - * @param string $sqlPartName - * @param mixed $sqlPart - * @param bool $append + * @param mixed $sqlPart * * @return $this This QueryBuilder instance. */ - public function add($sqlPartName, $sqlPart, $append = false) + public function add(string $sqlPartName, $sqlPart, bool $append = false) : self { $isArray = is_array($sqlPart); $isMultiple = is_array($this->sqlParts[$sqlPartName]); @@ -460,7 +452,7 @@ public function add($sqlPartName, $sqlPart, $append = false) * * @return $this This QueryBuilder instance. */ - public function select($select = null) + public function select($select = null) : self { $this->type = self::SELECT; @@ -488,7 +480,7 @@ public function select($select = null) * * @return $this This QueryBuilder instance. */ - public function addSelect($select = null) + public function addSelect($select = null) : self { $this->type = self::SELECT; @@ -517,7 +509,7 @@ public function addSelect($select = null) * * @return $this This QueryBuilder instance. */ - public function delete($delete = null, $alias = null) + public function delete(?string $delete = null, ?string $alias = null) : self { $this->type = self::DELETE; @@ -547,7 +539,7 @@ public function delete($delete = null, $alias = null) * * @return $this This QueryBuilder instance. */ - public function update($update = null, $alias = null) + public function update(?string $update = null, ?string $alias = null) : self { $this->type = self::UPDATE; @@ -580,7 +572,7 @@ public function update($update = null, $alias = null) * * @return $this This QueryBuilder instance. */ - public function insert($insert = null) + public function insert(?string $insert = null) : self { $this->type = self::INSERT; @@ -606,7 +598,7 @@ public function insert($insert = null) * * @return $this This QueryBuilder instance. */ - public function from($from, $alias = null) + public function from(string $from, ?string $alias = null) { return $this->add('from', [ 'table' => $from, @@ -631,7 +623,7 @@ public function from($from, $alias = null) * * @return $this This QueryBuilder instance. */ - public function join($fromAlias, $join, $alias, $condition = null) + public function join(string $fromAlias, string $join, string $alias, ?string $condition = null) { return $this->innerJoin($fromAlias, $join, $alias, $condition); } @@ -653,7 +645,7 @@ public function join($fromAlias, $join, $alias, $condition = null) * * @return $this This QueryBuilder instance. */ - public function innerJoin($fromAlias, $join, $alias, $condition = null) + public function innerJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) { return $this->add('join', [ $fromAlias => [ @@ -682,7 +674,7 @@ public function innerJoin($fromAlias, $join, $alias, $condition = null) * * @return $this This QueryBuilder instance. */ - public function leftJoin($fromAlias, $join, $alias, $condition = null) + public function leftJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) { return $this->add('join', [ $fromAlias => [ @@ -711,7 +703,7 @@ public function leftJoin($fromAlias, $join, $alias, $condition = null) * * @return $this This QueryBuilder instance. */ - public function rightJoin($fromAlias, $join, $alias, $condition = null) + public function rightJoin(string $fromAlias, string $join, string $alias, ?string $condition = null) { return $this->add('join', [ $fromAlias => [ @@ -738,7 +730,7 @@ public function rightJoin($fromAlias, $join, $alias, $condition = null) * * @return $this This QueryBuilder instance. */ - public function set($key, $value) + public function set(string $key, string $value) { return $this->add('set', $key . ' = ' . $value, true); } @@ -859,7 +851,7 @@ public function orWhere($where) * * @return $this This QueryBuilder instance. */ - public function groupBy($groupBy) + public function groupBy($groupBy) : self { if (empty($groupBy)) { return $this; @@ -885,7 +877,7 @@ public function groupBy($groupBy) * * @return $this This QueryBuilder instance. */ - public function addGroupBy($groupBy) + public function addGroupBy($groupBy) : self { if (empty($groupBy)) { return $this; @@ -915,7 +907,7 @@ public function addGroupBy($groupBy) * * @return $this This QueryBuilder instance. */ - public function setValue($column, $value) + public function setValue(string $column, string $value) : self { $this->sqlParts['values'][$column] = $value; @@ -937,7 +929,7 @@ public function setValue($column, $value) * ); * * - * @param mixed[] $values The values to specify for the insert query indexed by column names. + * @param array $values The values to specify for the insert query indexed by column names. * * @return $this This QueryBuilder instance. */ @@ -1018,7 +1010,7 @@ public function orHaving($having) * * @return $this This QueryBuilder instance. */ - public function orderBy($sort, $order = null) + public function orderBy(string $sort, ?string $order = null) { return $this->add('orderBy', $sort . ' ' . (! $order ? 'ASC' : $order), false); } @@ -1031,7 +1023,7 @@ public function orderBy($sort, $order = null) * * @return $this This QueryBuilder instance. */ - public function addOrderBy($sort, $order = null) + public function addOrderBy(string $sort, ?string $order = null) { return $this->add('orderBy', $sort . ' ' . (! $order ? 'ASC' : $order), true); } @@ -1039,11 +1031,9 @@ public function addOrderBy($sort, $order = null) /** * Gets a query part by its name. * - * @param string $queryPartName - * * @return mixed */ - public function getQueryPart($queryPartName) + public function getQueryPart(string $queryPartName) { return $this->sqlParts[$queryPartName]; } @@ -1051,9 +1041,9 @@ public function getQueryPart($queryPartName) /** * Gets all query parts. * - * @return mixed[] + * @return array */ - public function getQueryParts() + public function getQueryParts() : array { return $this->sqlParts; } @@ -1061,11 +1051,11 @@ public function getQueryParts() /** * Resets SQL parts. * - * @param string[]|null $queryPartNames + * @param array|null $queryPartNames * * @return $this This QueryBuilder instance. */ - public function resetQueryParts($queryPartNames = null) + public function resetQueryParts(?array $queryPartNames = null) : self { if ($queryPartNames === null) { $queryPartNames = array_keys($this->sqlParts); @@ -1081,11 +1071,9 @@ public function resetQueryParts($queryPartNames = null) /** * Resets a single SQL part. * - * @param string $queryPartName - * * @return $this This QueryBuilder instance. */ - public function resetQueryPart($queryPartName) + public function resetQueryPart(string $queryPartName) : self { $this->sqlParts[$queryPartName] = is_array($this->sqlParts[$queryPartName]) ? [] : null; @@ -1096,11 +1084,9 @@ public function resetQueryPart($queryPartName) } /** - * @return string - * * @throws QueryException */ - private function getSQLForSelect() + private function getSQLForSelect() : string { $query = 'SELECT ' . implode(', ', $this->sqlParts['select']); @@ -1122,9 +1108,9 @@ private function getSQLForSelect() } /** - * @return string[] + * @return array */ - private function getFromClauses() + private function getFromClauses() : array { $fromClauses = []; $knownAliases = []; @@ -1132,10 +1118,14 @@ private function getFromClauses() // Loop through all FROM clauses foreach ($this->sqlParts['from'] as $from) { if ($from['alias'] === null || $from['alias'] === $from['table']) { - $tableSql = $from['table']; + $tableSql = $from['table']; + + /** @var string $tableReference */ $tableReference = $from['table']; } else { - $tableSql = $from['table'] . ' ' . $from['alias']; + $tableSql = $from['table'] . ' ' . $from['alias']; + + /** @var string $tableReference */ $tableReference = $from['alias']; } @@ -1150,11 +1140,11 @@ private function getFromClauses() } /** - * @param string[] $knownAliases + * @param array $knownAliases * * @throws QueryException */ - private function verifyAllAliasesAreKnown(array $knownAliases) + private function verifyAllAliasesAreKnown(array $knownAliases) : void { foreach ($this->sqlParts['join'] as $fromAlias => $joins) { if (! isset($knownAliases[$fromAlias])) { @@ -1163,20 +1153,15 @@ private function verifyAllAliasesAreKnown(array $knownAliases) } } - /** - * @return bool - */ - private function isLimitQuery() + private function isLimitQuery() : bool { - return $this->maxResults !== null || $this->firstResult !== null; + return $this->maxResults !== null || $this->firstResult !== 0; } /** * Converts this instance into an INSERT string in SQL. - * - * @return string */ - private function getSQLForInsert() + private function getSQLForInsert() : string { return 'INSERT INTO ' . $this->sqlParts['from']['table'] . ' (' . implode(', ', array_keys($this->sqlParts['values'])) . ')' . @@ -1185,10 +1170,8 @@ private function getSQLForInsert() /** * Converts this instance into an UPDATE string in SQL. - * - * @return string */ - private function getSQLForUpdate() + private function getSQLForUpdate() : string { $from = $this->sqlParts['from']; @@ -1205,10 +1188,8 @@ private function getSQLForUpdate() /** * Converts this instance into a DELETE string in SQL. - * - * @return string */ - private function getSQLForDelete() + private function getSQLForDelete() : string { $from = $this->sqlParts['from']; @@ -1227,7 +1208,7 @@ private function getSQLForDelete() * * @return string The string representation of this QueryBuilder. */ - public function __toString() + public function __toString() : string { return $this->getSQL(); } @@ -1260,7 +1241,7 @@ public function __toString() * * @return string the placeholder name used. */ - public function createNamedParameter($value, $type = ParameterType::STRING, $placeHolder = null) + public function createNamedParameter($value, $type = ParameterType::STRING, ?string $placeHolder = null) : string { if ($placeHolder === null) { $this->boundCounter++; @@ -1289,11 +1270,8 @@ public function createNamedParameter($value, $type = ParameterType::STRING, $pla * * * @param mixed $value - * @param int $type - * - * @return string */ - public function createPositionalParameter($value, $type = ParameterType::STRING) + public function createPositionalParameter($value, int $type = ParameterType::STRING) : string { $this->boundCounter++; $this->setParameter($this->boundCounter, $value, $type); @@ -1302,14 +1280,11 @@ public function createPositionalParameter($value, $type = ParameterType::STRING) } /** - * @param string $fromAlias - * @param string[] $knownAliases - * - * @return string + * @param array $knownAliases * * @throws QueryException */ - private function getSQLForJoins($fromAlias, array &$knownAliases) + private function getSQLForJoins(string $fromAlias, array &$knownAliases) : string { $sql = ''; @@ -1334,8 +1309,6 @@ private function getSQLForJoins($fromAlias, array &$knownAliases) /** * Deep clone of all expression objects in the SQL parts. - * - * @return void */ public function __clone() {