Merge branch 'T12676-add-methods-to-interfaces' of https://github.com/niden/cphalcon into niden-T12676-add-methods-to-interfaces

* 'T12676-add-methods-to-interfaces' of https://github.com/niden/cphalcon:
  [#12676] - Updated the changelog
  [#12676] - Changes to the interfaces

Author: niden

CHANGELOG-4.0.md

@@ -27,6 +27,25 @@
 - Added `Phalcon\Paginator\RepositoryInterface` for repository the current state of `paginator` and also optional sets the aliases for properties repository [#10985](https://github.com/phalcon/cphalcon/pull/10985), [#10957](https://github.com/phalcon/cphalcon/issues/10957)
 - Added bind support to `Phalcon\Mvc\Model\Query\Builder`. The Query Builder has the same methods as `Phalcon\Mvc\Model\Query`; `getBindParams`, `setBindParams`, `getBindTypes` and `setBindTypes`. [#13368](https://github.com/phalcon/cphalcon/issues/13368)
 - Added `Phalcon\Html\Breadcrumbs`, a component that creates HTML code for breadcrumbs. [#13680](https://github.com/phalcon/cphalcon/issues/13680)
+- Added more methods to interfaces. 
+    - `Phalcon\Cli\Router\RouteInterface` - `delimiter`, `getDelimiter`                        
+    - `Phalcon\Cli\DispatcherInterface` - `setOptions`, `getOptions`
+    - `Phalcon\Db\AdapterInterface` - `fetchColumn`, `insertAsDict`, `updateAsDict`                              
+    - `Phalcon\Db\DialectInterface` - `registerCustomFunction`, `getCustomFunctions`, `getSqlExpression`                              
+    - `Phalcon\Di\ServiceInterface` - `getParameter`, `isResolved`
+    - `Phalcon\Events\ManagerInterface` - `hasListeners`                          
+    - `Phalcon\Mvc\Model\Query\BuilderInterface` - `distinct`, `getDistinct`, `forUpdate`, `offset`, `getOffset`                 
+    - `Phalcon\Mvc\Model\Transaction\ManagerInterface` - `setDbService`, `getDbService`, `setRollbackPendent`, `getRollbackPendent`           
+    - `Phalcon\Mvc\Model\CriteriaInterface` - `distinct`, `leftJoin`, `innerJoin`, `rightJoin`, `groupBy`, `having`, `cache`, `getColumns`, `getGroupBy`, `getHaving`                      
+    - `Phalcon\Mvc\Model\ManagerInterface` - `isVisibleModelProperty`, `keepSnapshots`, `isKeepingSnapshots`, `useDynamicUpdate`, `isUsingDynamicUpdate`, `addHasManyToMany`, `existsHasManyToMany`, `getRelationRecords`, `getHasManyToMany`, `registerNamespaceAlias`, `getNamespaceAlias`                       
+    - `Phalcon\Mvc\Model\MessageInterface` - `setModel`, `getModel`, `setCode`, `getCode`                       
+    - `Phalcon\Mvc\Model\QueryInterface` - `getSingleResult`, `setBindParams`, `getBindParams`, `setBindTypes`, `setSharedLock`, `getBindTypes`, `getSql`                         
+    - `Phalcon\Mvc\Model\RelationInterface` - `getParams`
+    - `Phalcon\Mvc\Model\ResultsetInterface` - `setHydrateMode`, `getHydrateMode`, `getMessages`, `update`, `delete`, `filter`
+    - `Phalcon\Mvc\ModelInterface` - `getModelsMetaData`
+    - `Phalcon\Session\AdapterInterface` - `setId`, `status`
+    - `Phalcon\Validation\MessageInteraface` - `getCode`, `setCode`                     
+    - `Phalcon\CryptInterface` - `setPadding`                                   
 - Added `attach()` to `Phalcon\Mvc\RouterInterface`
 - Added `Phalcon\Container`, a proxy container class to the `Phalcon\DI` implementing PSR-11 [#12295](https://github.com/phalcon/cphalcon/issues/12295)
 - Added `Phalcon\Acl\Adapter\Memory::getActiveKey`, `Phalcon\Acl\Adapter\Memory::activeFunctionCustomArgumentsCount` and `Phalcon\Acl\Adapter\Memory::getActiveFunction` to get latest key, number of custom arguments, and function used to acquire access
@@ -97,12 +116,7 @@
     - the `Phalcon\Session\Adapter\Files` using the name `session` 
     - the `Phalcon\Session\Bag` using the name `sessionBag` 
   [#12921](https://github.com/phalcon/cphalcon/issues/12921)
-- Changed the `Phalcon\Session` namespace by refactoring the component. `Phalcon\Session\Manager` is now the single component offering session manipulation by using adapters. Each adapter implements PHP's `SessionHandlerInterface`. Available adapters are `Phalcon\Session\Files`, `Phalcon\Session\Libmemcached`, `Phalcon\Session\Noop` and `Phalcon\Session\Redis`.  [#12921](https://github.com/phalcon/cphalcon/issues/12833), [11341](https://github.com/phalcon/cphalcon/issues/11341), [13535](https://github.com/phalcon/cphalcon/issues/13535)
-- Changed the `Phalcon\Tag` and `Phalcon\Html\Tag` to not output `type="text/javascript"` when the doctype is HTML5 [#13341](https://github.com/phalcon/cphalcon/issues/13341)
-- Changed `Phalcon\Http\RequestInterface::getUploadedFiles()` now returns an associative array if the second argument is passed as true
-- Changed the `Phalcon\Mvc\Url::get()` to correctly calculate the '/' and not produce URLs with double slashes [13495](https://github.com/phalcon/cphalcon/issues/13495)
-- Changed the license header for all `phalcon` files; Added same header in all tests as well as `declare(strict_types=1);` [#13684](https://github.com/phalcon/cphalcon/issues/13684)
-- Changed the `Phalcon\Mvc\Engine\Volt` to recognize `null` values when working with macros. [#13660](https://github.com/phalcon/cphalcon/issues/13660)
+- Changed the `Phalcon\Session` namespace by refactoring the component. `Phalcon\Session\Manager` is now the single component offering session manipulation by using adapters. Each adapter implements PHP's `SessionHandlerInterface`. Available adapters are `Phalcon\Session\Files`, `Phalcon\Session\Libmemcached`, `Phalcon\Session\Noop` and `Phalcon\Session\Redis`.  [#12921](https://github.com/phalcon/cphalcon/issues/12833), (https://github.com/phalcon/cphalcon/issues/11341), (https://github.com/phalcon/cphalcon/issues/13535)
 
 ## Removed
 - PHP < 7.2 no longer supported

phalcon/cli/dispatcherinterface.zep

@@ -54,4 +54,14 @@ interface DispatcherInterface extends DispatcherInterfaceBase
 	 * Returns the active task in the dispatcher
 	 */
 	public function getActiveTask() -> <TaskInterface>;
+
+	/**
+	 * Set the options to be dispatched
+	 */
+	public function setOptions(array options);
+
+	/**
+	 * Get dispatched options
+	 */
+	public function getOptions() -> array;
 }

phalcon/cli/router/routeinterface.zep

@@ -67,4 +67,13 @@ interface RouteInterface
 	 */
 	public static function reset() -> void;
 
+	/**
+	 * Set the routing delimiter
+	 */
+	public static function delimiter(string! delimiter = null);
+
+	/**
+	 * Get routing delimiter
+	 */
+	public static function getDelimiter() -> string;
 }

phalcon/cryptinterface.zep

@@ -17,6 +17,10 @@ namespace Phalcon;
  */
 interface CryptInterface
 {
+	/**
+	 * Changes the padding scheme used.
+	 */
+	public function setPadding(int! scheme) -> <CryptInterface>;
 
 	/**
 	 * Sets the cipher algorithm

phalcon/db/adapterinterface.zep

@@ -158,6 +158,26 @@ interface AdapterInterface
 	 */
 	public function fetchAll(string! sqlQuery, int fetchMode = 2, placeholders = null) -> array;
 
+	/**
+	 * Returns the n'th field of first row in a SQL query result
+	 *
+	 *<code>
+	 * // Getting count of robots
+	 * $robotsCount = $connection->fetchColumn("SELECT count(*) FROM robots");
+	 * print_r($robotsCount);
+	 *
+	 * // Getting name of last edited robot
+	 * $robot = $connection->fetchColumn(
+	 *     "SELECT id, name FROM robots order by modified desc",
+	 *     1
+	 * );
+	 * print_r($robot);
+	 *</code>
+	 *
+	 * @param  int|string column
+	 */
+	public function fetchColumn(string sqlQuery, array placeholders = [], var column = 0) -> string | bool;
+
 	/**
 	 * Returns the first row in a SQL query result
 	 *
@@ -250,6 +270,28 @@ interface AdapterInterface
 	 */
 	public function insert(string table, array! values, fields = null, dataTypes = null) -> bool;
 
+	/**
+	 * Inserts data into a table using custom RBDM SQL syntax
+	 *
+	 * <code>
+	 * // Inserting a new robot
+	 * $success = $connection->insertAsDict(
+	 *     "robots",
+	 *     [
+	 *         "name" => "Astro Boy",
+	 *         "year" => 1952,
+	 *     ]
+	 * );
+	 *
+	 * // Next SQL sentence is sent to the database system
+	 * INSERT INTO `robots` (`name`, `year`) VALUES ("Astro boy", 1952);
+	 * </code>
+	 *
+	 * @param 	array data
+	 * @param 	array dataTypes
+	 */
+	public function insertAsDict(string table, data, var dataTypes = null) -> bool;
+
 	/**
 	 * Returns if nested transactions should use savepoints
 	 */
@@ -344,6 +386,30 @@ interface AdapterInterface
 	 */
 	public function update(string table, fields, values, whereCondition = null, dataTypes = null) -> bool;
 
+	/**
+	 * Updates data on a table using custom RBDM SQL syntax
+	 * Another, more convenient syntax
+	 *
+	 * <code>
+	 * // Updating existing robot
+	 * $success = $connection->updateAsDict(
+	 *     "robots",
+	 *     [
+	 *         "name" => "New Astro Boy",
+	 *     ],
+	 *     "id = 101"
+	 * );
+	 *
+	 * // Next SQL sentence is sent to the database system
+	 * UPDATE `robots` SET `name` = "Astro boy" WHERE id = 101
+	 * </code>
+	 *
+	 * @param 	array data
+	 * @param 	string whereCondition
+	 * @param 	array dataTypes
+	 */
+	public function updateAsDict(string table, var data, var whereCondition = null, var dataTypes = null) -> bool;
+
 	/**
 	 * Check whether the database system requires an explicit value for identity columns
 	 */

phalcon/db/dialectinterface.zep

@@ -179,4 +179,18 @@ interface DialectInterface
 	 */
 	public function rollbackSavepoint(string! name) -> string;
 
+	/**
+	 * Registers custom SQL functions
+	 */
+	public function registerCustomFunction(string name, callable customFunction) -> <Dialect>;
+
+	/**
+	 * Returns registered functions
+	 */
+	public function getCustomFunctions() -> array;
+
+	/**
+	 * Transforms an intermediate representation for an expression into a database system valid expression
+	 */
+	public function getSqlExpression(array! expression, string escapeChar = null, bindCounts = null) -> string;
 }

phalcon/di/serviceinterface.zep

@@ -56,6 +56,18 @@ interface ServiceInterface
 	 */
 	public function setParameter(int position, array! parameter) -> <ServiceInterface>;
 
+	/**
+	 * Returns a parameter in a specific position
+	 *
+	 * @return array
+	 */
+	public function getParameter(int position);
+
+	/**
+	 * Returns true if the service was resolved
+	 */
+	public function isResolved() -> bool;
+
 	/**
 	 * Restore the internal state of a service
 	 */

phalcon/events/managerinterface.zep

@@ -48,6 +48,11 @@ interface ManagerInterface
 	 */
 	public function fire(string! eventType, source, data = null);
 
+	/**
+	 * Check whether certain type of event has listeners
+	 */
+	public function hasListeners(string! type) -> bool;
+
 	/**
 	 * Returns all the attached listeners of a certain type
 	 */

phalcon/mvc/model/criteriainterface.zep

@@ -173,4 +173,70 @@ interface CriteriaInterface
 	 */
 	public function execute() -> <ResultsetInterface>;
 
+	/**
+	 * Sets SELECT DISTINCT / SELECT ALL flag
+	 */
+	 public function distinct(var distinct) -> <CriteriaInterface>;
+
+	/**
+	 * Adds an INNER join to the query
+	 *
+	 *<code>
+	 * $criteria->innerJoin("Robots");
+	 * $criteria->innerJoin("Robots", "r.id = RobotsParts.robots_id");
+	 * $criteria->innerJoin("Robots", "r.id = RobotsParts.robots_id", "r");
+	 *</code>
+	 */
+	public function innerJoin(string! model, var conditions = null, var alias = null) -> <CriteriaInterface>;
+
+	/**
+	 * Adds a LEFT join to the query
+	 *
+	 *<code>
+	 * $criteria->leftJoin("Robots", "r.id = RobotsParts.robots_id", "r");
+	 *</code>
+	 */
+	public function leftJoin(string! model, var conditions = null, var alias = null) -> <CriteriaInterface>;
+
+	/**
+	 * Adds a RIGHT join to the query
+	 *
+	 *<code>
+	 * $criteria->rightJoin("Robots", "r.id = RobotsParts.robots_id", "r");
+	 *</code>
+	 */
+	public function rightJoin(string! model, conditions = null, alias = null) -> <CriteriaInterface>;
+
+	/**
+	 * Adds the group-by clause to the criteria
+	 */
+	public function groupBy(var group) -> <CriteriaInterface>;
+
+	/**
+	 * Adds the having clause to the criteria
+	 */
+	public function having(var having) -> <CriteriaInterface>;
+
+	/**
+	 * Sets the cache options in the criteria
+	 * This method replaces all previously set cache options
+	 */
+	public function cache(array! cache) -> <CriteriaInterface>;
+
+	/**
+	 * Returns the columns to be queried
+	 *
+	 * @return string|array|null
+	 */
+	public function getColumns() -> string | null;
+
+	/**
+	 * Returns the group clause in the criteria
+	 */
+	public function getGroupBy();
+
+	/**
+	 * Returns the having clause in the criteria
+	 */
+	public function getHaving();
 }

phalcon/mvc/model/managerinterface.zep

@@ -247,4 +247,74 @@ interface ManagerInterface
 	 */
 	public function getRelationByAlias(string! modelName, string! alias) -> <Relation> | bool;
 
+	/**
+	 * Check whether a model property is declared as public.
+	 *
+	 * <code>
+	 * $isPublic = $manager->isVisibleModelProperty(
+	 *     new Robots(),
+	 *     "name"
+	 * );
+	 * </code>
+	 */
+	public final function isVisibleModelProperty(<ModelInterface> model, string property) -> bool;
+
+	/**
+	 * Sets if a model must keep snapshots
+	 */
+	public function keepSnapshots(<ModelInterface> model, bool keepSnapshots) -> void;
+
+	/**
+	 * Checks if a model is keeping snapshots for the queried records
+	 */
+	public function isKeepingSnapshots(<ModelInterface> model) -> bool;
+
+	/**
+	 * Sets if a model must use dynamic update instead of the all-field update
+	 */
+	public function useDynamicUpdate(<ModelInterface> model, bool dynamicUpdate);
+
+	/**
+	 * Checks if a model is using dynamic update instead of all-field update
+	 */
+	public function isUsingDynamicUpdate(<ModelInterface> model) -> bool;
+
+	/**
+	 * Setups a relation n-m between two models
+	 *
+	 * @param	string fields
+	 * @param	string intermediateFields
+	 * @param	string intermediateReferencedFields
+	 * @param	string referencedFields
+	 * @param   array options
+	 */
+	public function addHasManyToMany(<ModelInterface> model, var fields, string! intermediateModel,
+		var intermediateFields, var intermediateReferencedFields, string! referencedModel, var referencedFields, var options = null) -> <RelationInterface>;
+
+	/**
+	 * Checks whether a model has a hasManyToMany relation with another model
+	 */
+	public function existsHasManyToMany(string! modelName, string! modelRelation) -> bool;
+
+	/**
+	 * Helper method to query records based on a relation definition
+	 *
+	 * @return \Phalcon\Mvc\Model\Resultset\Simple|Phalcon\Mvc\Model\Resultset\Simple|int|false
+	 */
+	public function getRelationRecords(<RelationInterface> relation, string! method, <ModelInterface> record, var parameters = null);
+
+	/**
+	 * Gets hasManyToMany relations defined on a model
+	 */
+	public function getHasManyToMany(<ModelInterface> model) -> <RelationInterface[]> | array;
+
+	/**
+	 * Registers shorter aliases for namespaces in PHQL statements
+	 */
+	public function registerNamespaceAlias(string alias, string namespaceName) -> void;
+
+	/**
+	 * Returns a real namespace from its alias
+	 */
+	public function getNamespaceAlias(string! alias) -> string;
 }

phalcon/mvc/model/query/builderinterface.zep

@@ -215,4 +215,34 @@ interface BuilderInterface
 	 * Returns default bind types
 	 */
 	public function getBindTypes() -> array;
+
+	/**
+	 * Sets SELECT DISTINCT / SELECT ALL flag
+	 *
+	 *<code>
+	 * $builder->distinct("status");
+	 * $builder->distinct(null);
+	 *</code>
+	 */
+	public function distinct(var distinct) -> <BuilderInterface>;
+
+	/**
+	 * Returns SELECT DISTINCT / SELECT ALL flag
+	 */
+	public function getDistinct() -> bool;
+
+	/**
+	 * Sets a FOR UPDATE clause
+	 *
+	 *<code>
+	 * $builder->forUpdate(true);
+	 *</code>
+	 */
+	public function forUpdate(bool forUpdate) -> <BuilderInterface>;
+
+
+	/**
+	 * Returns the current OFFSET clause
+	 */
+	public function getOffset() -> int;
 }