diff --git a/src/DataMapper/Query/AbstractQuery.php b/src/DataMapper/Query/AbstractQuery.php index 2777e31..9c87876 100644 --- a/src/DataMapper/Query/AbstractQuery.php +++ b/src/DataMapper/Query/AbstractQuery.php @@ -127,8 +127,82 @@ public function quoteIdentifier(string $name, int $type = \PDO::PARAM_STR): stri /** * Resets the internal array + * + * @return void + */ + public function reset(): void + { + } + + /** + * Resets the columns + * + * @return void + */ + public function resetColumns(): void + { + } + + /** + * Resets the from + * + * @return void + */ + public function resetFrom(): void + { + } + + /** + * Resets the where + * + * @return void + */ + public function resetWhere(): void + { + } + + /** + * Resets the group by + * + * @return void + */ + public function resetGroupBy(): void + { + } + + /** + * Resets the having + * + * @return void + */ + public function resetHaving(): void + { + } + + /** + * Resets the order by + * + * @return void + */ + public function resetOrderBy(): void + { + } + + /** + * Resets the limit and offset + * + * @return void + */ + public function resetLimit(): void + { + } + + /** + * Resets the flags + * + * @return void */ - public function reset() + public function resetFlags(): void { } diff --git a/src/DataMapper/Query/Select.php b/src/DataMapper/Query/Select.php index b75dfdf..2e715ba 100644 --- a/src/DataMapper/Query/Select.php +++ b/src/DataMapper/Query/Select.php @@ -212,9 +212,9 @@ public function orHaving(string $condition, $value = null, int $type = -1): Sele /** * Resets the internal collections * - * @return Select + * @return void */ - public function reset(): Select + public function reset(): void { } diff --git a/src/Db/AbstractDb.php b/src/Db/AbstractDb.php deleted file mode 100644 index bc32871..0000000 --- a/src/Db/AbstractDb.php +++ /dev/null @@ -1,68 +0,0 @@ - - * - * For the full copyright and license information, please view the LICENSE.txt - * file that was distributed with this source code. - */ -namespace Phalcon\Db; - -use PDO as Pdo; - -/** - * Phalcon\Db and its related classes provide a simple SQL database interface - * for Phalcon Framework. The Phalcon\Db is the basic class you use to connect - * your PHP application to an RDBMS. There is a different adapter class for each - * brand of RDBMS. - * - * This component is intended to lower level database operations. If you want to - * interact with databases using higher level of abstraction use - * Phalcon\Mvc\Model. - * - * Phalcon\Db\AbstractDb is an abstract class. You only can use it with a - * database adapter like Phalcon\Db\Adapter\Pdo - * - * ```php - * use Phalcon\Db; - * use Phalcon\Db\Exception; - * use Phalcon\Db\Adapter\Pdo\Mysql as MysqlConnection; - * - * try { - * $connection = new MysqlConnection( - * [ - * "host" => "192.168.0.11", - * "username" => "sigma", - * "password" => "secret", - * "dbname" => "blog", - * "port" => "3306", - * ] - * ); - * - * $result = $connection->query( - * "SELECT FROM robots LIMIT 5" - * ); - * - * $result->setFetchMode(Enum::FETCH_NUM); - * - * while ($robot = $result->fetch()) { - * print_r($robot); - * } - * } catch (Exception $e) { - * echo $e->getMessage(), PHP_EOL; - * } - * ``` - */ -abstract class AbstractDb -{ - /** - * Enables/disables options in the Database component - * - * @param array $options - * @return void - */ - public static function setup(array $options): void - { - } -} diff --git a/src/Db/Adapter/AbstractAdapter.php b/src/Db/Adapter/AbstractAdapter.php index 40d76b0..ad4b5c4 100644 --- a/src/Db/Adapter/AbstractAdapter.php +++ b/src/Db/Adapter/AbstractAdapter.php @@ -22,7 +22,49 @@ use Phalcon\Events\ManagerInterface; /** - * Base class for Phalcon\Db\Adapter adapters + * Base class for Phalcon\Db\Adapter adapters. + * + * This class and its related classes provide a simple SQL database interface + * for Phalcon Framework. The Phalcon\Db is the basic class you use to connect + * your PHP application to an RDBMS. There is a different adapter class for each + * brand of RDBMS. + * + * This component is intended to lower level database operations. If you want to + * interact with databases using higher level of abstraction use + * Phalcon\Mvc\Model. + * + * Phalcon\Db\AbstractDb is an abstract class. You only can use it with a + * database adapter like Phalcon\Db\Adapter\Pdo + * + * ```php + * use Phalcon\Db; + * use Phalcon\Db\Exception; + * use Phalcon\Db\Adapter\Pdo\Mysql as MysqlConnection; + * + * try { + * $connection = new MysqlConnection( + * [ + * "host" => "192.168.0.11", + * "username" => "sigma", + * "password" => "secret", + * "dbname" => "blog", + * "port" => "3306", + * ] + * ); + * + * $result = $connection->query( + * "SELECT FROM co_invoices LIMIT 5" + * ); + * + * $result->setFetchMode(Enum::FETCH_NUM); + * + * while ($invoice = $result->fetch()) { + * print_r($invoice); + * } + * } catch (Exception $e) { + * echo $e->getMessage(), PHP_EOL; + * } + * ``` */ abstract class AbstractAdapter implements \Phalcon\Db\Adapter\AdapterInterface, \Phalcon\Events\EventsAwareInterface { @@ -808,6 +850,16 @@ public function setNestedTransactionsWithSavepoints(bool $nestedTransactionsWith { } + /** + * Enables/disables options in the Database component + * + * @param array $options + * @return void + */ + public static function setup(array $options): void + { + } + /** * Returns a SQL modified with a LOCK IN SHARE MODE clause * diff --git a/src/Db/Adapter/Pdo/Mysql.php b/src/Db/Adapter/Pdo/Mysql.php index 1b25259..20a3b00 100644 --- a/src/Db/Adapter/Pdo/Mysql.php +++ b/src/Db/Adapter/Pdo/Mysql.php @@ -48,25 +48,6 @@ class Mysql extends \Phalcon\Db\Adapter\Pdo\AbstractPdo */ protected $type = 'mysql'; - /** - * Constructor for Phalcon\Db\Adapter\Pdo - * - * @param array $descriptor = [ - * 'host' => 'localhost', - * 'port' => '3306', - * 'dbname' => 'blog', - * 'username' => 'sigma' - * 'password' => 'secret' - * 'dialectClass' => null, - * 'options' => [], - * 'dsn' => null, - * 'charset' => 'utf8mb4' - * ] - */ - public function __construct(array $descriptor) - { - } - /** * Adds a foreign key to a table * diff --git a/src/Di/Di.php b/src/Di/Di.php index d6d36c8..1dbf969 100644 --- a/src/Di/Di.php +++ b/src/Di/Di.php @@ -232,7 +232,7 @@ protected function loadFromConfig(\Phalcon\Config\ConfigInterface $config): void * ]; * ``` * - * @link https://docs.phalcon.io/en/latest/reference/di.html + * @link https://docs.phalcon.io/latest/di/ * @param string $filePath * @return void */ @@ -271,7 +271,7 @@ public function loadFromPhp(string $filePath): void * className: \Acme\User * ``` * - * @link https://docs.phalcon.io/en/latest/reference/di.html + * @link https://docs.phalcon.io/latest/di/ * @param string $filePath * @param array $callbacks * @return void diff --git a/src/Filter/Validation/Validator/Uniqueness.php b/src/Filter/Validation/Validator/Uniqueness.php index 63a99f3..dbe9545 100644 --- a/src/Filter/Validation/Validator/Uniqueness.php +++ b/src/Filter/Validation/Validator/Uniqueness.php @@ -99,12 +99,12 @@ class Uniqueness extends AbstractCombinedFieldsValidator * Constructor * * @param array $options = [ - * 'message' => '', - * 'template' => '', + * 'message' => '', + * 'template' => '', * 'allowEmpty' => false, - * 'convert' => null, - * 'model' => null, - * 'except' => null + * 'convert' => null, + * 'model' => null, + * 'except' => null * ] */ public function __construct(array $options = []) diff --git a/src/Html/Helper/Input/Select.php b/src/Html/Helper/Input/Select.php index d86b907..722df9a 100644 --- a/src/Html/Helper/Input/Select.php +++ b/src/Html/Helper/Input/Select.php @@ -13,10 +13,6 @@ /** * Class Select - * - * @property string $elementTag - * @property bool $inOptGroup - * @property string $selected */ class Select extends AbstractList { diff --git a/src/Mvc/Model.php b/src/Mvc/Model.php index 689437b..16c92d4 100644 --- a/src/Mvc/Model.php +++ b/src/Mvc/Model.php @@ -1515,26 +1515,36 @@ public static function sum($parameters = null): ResultsetInterface|float * ``` * * @param array $columns + * @param mixed $useGetter * @return array */ - public function toArray($columns = null): array + public function toArray($columns = null, $useGetter = true): array { } /** * Updates a model instance. If the instance doesn't exist in the - * persistence it will throw an exception. Returning true on success or - * false otherwise. + * persistence it will throw an exception. Returning `true` on success or + * `false` otherwise. * * ```php - * // Updating a robot name - * $robot = Robots::findFirst("id = 100"); + * name = "Biomass"; + * use MyApp\Models\Invoices; + * + * $invoice = Invoices::findFirst('inv_id = 4'); * - * $robot->update(); + * $invoice->inv_total = 120; + * + * $invoice->update(); * ``` * + * !!! warning "NOTE" + * + * When retrieving the record with `findFirst()`, you need to get the full + * object back (no `columns` definition) but also retrieve it using the + * primary key. If not, the ORM will issue an `INSERT` instead of `UPDATE`. + * * @return bool */ public function update(): bool diff --git a/src/Mvc/Model/Criteria.php b/src/Mvc/Model/Criteria.php index 89669e7..4f2a81a 100644 --- a/src/Mvc/Model/Criteria.php +++ b/src/Mvc/Model/Criteria.php @@ -16,19 +16,19 @@ use Phalcon\Mvc\Model\Query\BuilderInterface; /** - * Phalcon\Mvc\Model\Criteria - * * This class is used to build the array parameter required by * Phalcon\Mvc\Model::find() and Phalcon\Mvc\Model::findFirst() using an * object-oriented interface. * * ```php - * $robots = Robots::query() - * ->where("type = :type:") - * ->andWhere("year < 2000") - * ->bind(["type" => "mechanical"]) + * where("inv_cst_id = :customerId:") + * ->andWhere("inv_created_date < '2000-01-01'") + * ->bind(["customerId" => 1]) * ->limit(5, 10) - * ->orderBy("name") + * ->orderBy("inv_title") * ->execute(); * ``` */ @@ -122,13 +122,46 @@ public function cache(array $cache): CriteriaInterface } /** - * Sets the columns to be queried + * Sets the columns to be queried. The columns can be either a `string` or + * an `array` of strings. If the argument is a (single, non-embedded) string, + * its content can specify one or more columns, separated by commas, the same + * way that one uses the SQL select statement. You can use aliases, aggregate + * functions, etc. If you need to reference other models you will need to + * reference them with their namespaces. + * + * When using an array as a parameter, you will need to specify one field + * per array element. If a non-numeric key is defined in the array, it will + * be used as the alias in the query * * ```php + * columns("id, category"); + * + * // Array, one column per element * $criteria->columns( * [ - * "id", - * "name", + * "inv_id", + * "inv_total", + * ] + * ); + * + * // Array with named key. The name of the key acts as an + * // alias (`AS` clause) + * $criteria->columns( + * [ + * "inv_cst_id", + * "total_invoices" => "COUNT()", + * ] + * ); + * + * // Different models + * $criteria->columns( + * [ + * "\Phalcon\Models\Invoices.", + * "\Phalcon\Models\Customers.cst_name_first", + * "\Phalcon\Models\Customers.cst_name_last", * ] * ); * ``` @@ -153,10 +186,11 @@ public function conditions(string $conditions): CriteriaInterface /** * Creates a query builder from criteria. * - * ```php - * $builder = Robots::query() - * ->where("type = :type:") - * ->bind(["type" => "mechanical"]) + * where("inv_cst_id = :customerId:") + * ->bind(["customerId" => 1]) * ->createBuilder(); * ``` * @@ -322,19 +356,21 @@ public function having($having): CriteriaInterface * Adds an INNER join to the query * * ```php + * innerJoin( - * Robots::class + * Invoices::class * ); * * $criteria->innerJoin( - * Robots::class, - * "r.id = RobotsParts.robots_id" + * Invoices::class, + * "inv_cst_id = Customers.cst_id" * ); * * $criteria->innerJoin( - * Robots::class, - * "r.id = RobotsParts.robots_id", - * "r" + * Invoices::class, + * "i.inv_cst_id = Customers.cst_id", + * "i" * ); * ``` * @@ -366,25 +402,27 @@ public function inWhere(string $expr, array $values): CriteriaInterface * Adds an INNER join to the query * * ```php + * join( - * Robots::class + * Invoices::class * ); * * $criteria->join( - * Robots::class, - * "r.id = RobotsParts.robots_id" + * Invoices::class, + * "inv_cst_id = Customers.cst_id" * ); * * $criteria->join( - * Robots::class, - * "r.id = RobotsParts.robots_id", - * "r" + * Invoices::class, + * "i.inv_cst_id = Customers.cst_id", + * "i" * ); * * $criteria->join( - * Robots::class, - * "r.id = RobotsParts.robots_id", - * "r", + * Invoices::class, + * "i.inv_cst_id = Customers.cst_id", + * "i", * "LEFT" * ); * ``` @@ -403,10 +441,12 @@ public function join(string $model, $conditions = null, $alias = null, $type = n * Adds a LEFT join to the query * * ```php + * leftJoin( - * Robots::class, - * "r.id = RobotsParts.robots_id", - * "r" + * Invoices::class, + * "i.inv_cst_id = Customers.cst_id", + * "i" * ); * ``` * @@ -493,10 +533,12 @@ public function orWhere(string $conditions, $bindParams = null, $bindTypes = nul * Adds a RIGHT join to the query * * ```php + * rightJoin( - * Robots::class, - * "r.id = RobotsParts.robots_id", - * "r" + * Invoices::class, + * "i.inv_cst_id = Customers.cst_id", + * "i" * ); * ``` * diff --git a/src/Mvc/Model/Manager.php b/src/Mvc/Model/Manager.php index e78bbdf..996f842 100644 --- a/src/Mvc/Model/Manager.php +++ b/src/Mvc/Model/Manager.php @@ -724,6 +724,8 @@ public function getRelationsBetween(string $first, string $second): bool|array * * @param string $modelName * @param string $key + * + * @return mixed */ public function getReusableRecords(string $modelName, string $key) { diff --git a/src/Mvc/Model/Query/Builder.php b/src/Mvc/Model/Query/Builder.php index cf29076..ba9d274 100644 --- a/src/Mvc/Model/Query/Builder.php +++ b/src/Mvc/Model/Query/Builder.php @@ -260,27 +260,51 @@ public function betweenWhere(string $expr, $minimum, $maximum, string $operator } /** - * Sets the columns to be queried + * Sets the columns to be queried. The columns can be either a `string` or + * an `array` of strings. If the argument is a (single, non-embedded) string, + * its content can specify one or more columns, separated by commas, the same + * way that one uses the SQL select statement. You can use aliases, aggregate + * functions, etc. If you need to reference other models you will need to + * reference them with their namespaces. + * + * When using an array as a parameter, you will need to specify one field + * per array element. If a non-numeric key is defined in the array, it will + * be used as the alias in the query * * ```php - * $builder->columns("id, name"); + * columns("id, category"); + * + * // Array, one column per element + * $builder->columns( + * [ + * "inv_id", + * "inv_total", + * ] + * ); * + * // Array with named key. The name of the key acts as an + * // alias (`AS` clause) * $builder->columns( * [ - * "id", - * "name", + * "inv_cst_id", + * "total_invoices" => "COUNT()", * ] * ); * + * // Different models * $builder->columns( * [ - * "name", - * "number" => "COUNT()", + * "\Phalcon\Models\Invoices.", + * "\Phalcon\Models\Customers.cst_name_first", + * "\Phalcon\Models\Customers.cst_name_last", * ] * ); * ``` * - * @param mixed $columns + * @param string|array $columns * @return BuilderInterface */ public function columns($columns): BuilderInterface diff --git a/src/Mvc/Model/Query/BuilderInterface.php b/src/Mvc/Model/Query/BuilderInterface.php index 5f1aba7..084a436 100644 --- a/src/Mvc/Model/Query/BuilderInterface.php +++ b/src/Mvc/Model/Query/BuilderInterface.php @@ -54,7 +54,48 @@ public function andWhere(string $conditions, array $bindParams = [], array $bind public function betweenWhere(string $expr, $minimum, $maximum, string $operator = BuilderInterface::OPERATOR_AND): BuilderInterface; /** - * Sets the columns to be queried + * Sets the columns to be queried. The columns can be either a `string` or + * an `array` of strings. If the argument is a (single, non-embedded) string, + * its content can specify one or more columns, separated by commas, the same + * way that one uses the SQL select statement. You can use aliases, aggregate + * functions, etc. If you need to reference other models you will need to + * reference them with their namespaces. + * + * When using an array as a parameter, you will need to specify one field + * per array element. If a non-numeric key is defined in the array, it will + * be used as the alias in the query + * + * ```php + * columns("id, name"); + * + * // Array, one column per element + * $builder->columns( + * [ + * "id", + * "name", + * ] + * ); + * + * // Array, named keys. The name of the key acts as an alias (`AS` clause) + * $builder->columns( + * [ + * "name", + * "number" => "COUNT()", + * ] + * ); + * + * // Different models + * $builder->columns( + * [ + * "\Phalcon\Models\Invoices.", + * "\Phalcon\Models\Customers.cst_name_first", + * "\Phalcon\Models\Customers.cst_name_last", + * ] + * ); + * ``` * * @param string|array $columns * @return BuilderInterface diff --git a/src/Mvc/Model/Resultset/Complex.php b/src/Mvc/Model/Resultset/Complex.php index fb9e19a..711f8e7 100644 --- a/src/Mvc/Model/Resultset/Complex.php +++ b/src/Mvc/Model/Resultset/Complex.php @@ -73,7 +73,8 @@ public function toArray(): array } /** - * Serializing a resultset will dump all related rows into a big array + * Serializing a resultset will dump all related rows into a big array, + * serialize it and return the resulting string * * @return string */ diff --git a/src/Mvc/View/Engine/Volt/Compiler.php b/src/Mvc/View/Engine/Volt/Compiler.php index c97fba4..9acb183 100644 --- a/src/Mvc/View/Engine/Volt/Compiler.php +++ b/src/Mvc/View/Engine/Volt/Compiler.php @@ -354,9 +354,61 @@ public function compileReturn(array $statement): string } /** - * Compiles a "set" statement returning PHP code + * Compiles a "set" statement returning PHP code. The method accepts an + * array produced by the Volt parser and creates the `set` statement in PHP. + * This method is not particularly useful in development, since it requires + * advanced knowledge of the Volt parser. + * + * ```php + * 306, + * "assignments" => [ + * [ + * "variable" => [ + * "type" => 265, + * "value" => "a", + * "file" => "eval code", + * "line" => 1 + * ], + * "op" => 61, + * "expr" => [ + * "type" => 360, + * "left" => [ + * [ + * "expr" => [ + * "type" => 258, + * "value" => "1", + * "file" => "eval code", + * "line" => 1 + * ], + * "name" => "first", + * "file" => "eval code", + * "line" => 1 + * ] + * ], + * "file" => "eval code", + * "line" => 1 + * ], + * "file" => "eval code", + * "line" => 1 + * ] + * ] + * ]; + * + * echo $compiler->compileSet($source); + * // 1]; ?>"; + * ``` + * + * @param array $statement * - * @param array $statement * * @throws \Phalcon\Mvc\View\Engine\Volt\Exception * @return string */ diff --git a/src/Storage/Adapter/Apcu.php b/src/Storage/Adapter/Apcu.php index c48fb2d..9121b30 100644 --- a/src/Storage/Adapter/Apcu.php +++ b/src/Storage/Adapter/Apcu.php @@ -149,11 +149,9 @@ protected function doGet(string $key) * @todo Remove the below once we get traits * @param mixed $key * @param int $step - * @param mixed $success - * @param int $ttl * @return bool|int */ - protected function phpApcuDec($key, int $step = 1, $success = null, int $ttl = 0): int|bool + protected function phpApcuDec($key, int $step = 1): int|bool { } @@ -176,20 +174,17 @@ protected function phpApcuExists($key): bool|array /** * @param mixed $key * @param int $step - * @param mixed $success - * @param int $ttl * @return bool|int */ - protected function phpApcuInc($key, int $step = 1, $success = null, int $ttl = 0): int|bool + protected function phpApcuInc($key, int $step = 1): int|bool { } /** * @param mixed $key - * @param mixed $success * @return mixed */ - protected function phpApcuFetch($key, $success = null): mixed + protected function phpApcuFetch($key): mixed { }