From 98fcad548f606d56725e3095e67aee6a0088a979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Vo=C5=99=C3=AD=C5=A1ek?= Date: Sat, 2 Dec 2023 14:51:38 +0100 Subject: [PATCH] Improve callable phpdocs --- Database/Query.php | 64 +++++++++++------------ Editor.php | 23 +++++---- Editor/Field.php | 90 +++++++++++++++++---------------- Editor/Join.php | 19 +++---- Editor/Options.php | 5 +- Editor/SearchBuilderOptions.php | 7 +-- Editor/SearchPaneOptions.php | 7 +-- Editor/Upload.php | 51 ++++++++++--------- 8 files changed, 137 insertions(+), 129 deletions(-) diff --git a/Database/Query.php b/Database/Query.php index 63bf004..8444799 100644 --- a/Database/Query.php +++ b/Database/Query.php @@ -610,15 +610,15 @@ public function set($set, $val = null, $bind = true) * Can be used in two different ways, as where( field, value ) or as an array of * conditions to use: where( array('fieldName', ...), array('value', ...) ); * - * @param string|string[]|callable $key Single field name, or an array of field names. - * If given as a function (i.e. a closure), the function is called, passing the - * query itself in as the only parameter, so the function can add extra conditions - * with parentheses around the additional parameters. - * @param string|string[] $value Single field value, or an array of - * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending - * on the value of `$op` which should be `=` or `!=`. - * @param string $op Condition operator: <, >, = etc - * @param bool $bind Escape the value (true, default) or not (false). + * @param string|string[]|\Closure($this): void $key Single field name, or an array of field names. + * If given as a function (i.e. a closure), the function is called, passing the + * query itself in as the only parameter, so the function can add extra conditions + * with parentheses around the additional parameters. + * @param string|string[] $value Single field value, or an array of + * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending + * on the value of `$op` which should be `=` or `!=`. + * @param string $op Condition operator: <, >, = etc + * @param bool $bind Escape the value (true, default) or not (false). * * @return $this * @@ -661,15 +661,15 @@ public function where($key, $value = null, $op = '=', $bind = true) * Can be used in two different ways, as where( field, value ) or as an array of * conditions to use: where( array('fieldName', ...), array('value', ...) ); * - * @param string|string[]|callable $key Single field name, or an array of field names. - * If given as a function (i.e. a closure), the function is called, passing the - * query itself in as the only parameter, so the function can add extra conditions - * with parentheses around the additional parameters. - * @param string|string[] $value Single field value, or an array of - * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending - * on the value of `$op` which should be `=` or `!=`. - * @param string $op Condition operator: <, >, = etc - * @param bool $bind Escape the value (true, default) or not (false). + * @param string|string[]|\Closure($this): void $key Single field name, or an array of field names. + * If given as a function (i.e. a closure), the function is called, passing the + * query itself in as the only parameter, so the function can add extra conditions + * with parentheses around the additional parameters. + * @param string|string[] $value Single field value, or an array of + * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending + * on the value of `$op` which should be `=` or `!=`. + * @param string $op Condition operator: <, >, = etc + * @param bool $bind Escape the value (true, default) or not (false). * * @return $this */ @@ -684,15 +684,15 @@ public function and_where($key, $value = null, $op = '=', $bind = true) * Can be used in two different ways, as where( field, value ) or as an array of * conditions to use: where( array('fieldName', ...), array('value', ...) ); * - * @param string|string[]|callable $key Single field name, or an array of field names. - * If given as a function (i.e. a closure), the function is called, passing the - * query itself in as the only parameter, so the function can add extra conditions - * with parentheses around the additional parameters. - * @param string|string[] $value Single field value, or an array of - * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending - * on the value of `$op` which should be `=` or `!=`. - * @param string $op Condition operator: <, >, = etc - * @param bool $bind Escape the value (true, default) or not (false). + * @param string|string[]|\Closure($this): void $key Single field name, or an array of field names. + * If given as a function (i.e. a closure), the function is called, passing the + * query itself in as the only parameter, so the function can add extra conditions + * with parentheses around the additional parameters. + * @param string|string[] $value Single field value, or an array of + * values. Can be null to search for `IS NULL` or `IS NOT NULL` (depending + * on the value of `$op` which should be `=` or `!=`. + * @param string $op Condition operator: <, >, = etc + * @param bool $bind Escape the value (true, default) or not (false). * * @return $this */ @@ -727,11 +727,11 @@ public function or_where($key, $value = null, $op = '=', $bind = true) * define if a grouping bracket should be opened or closed in the query. * This method is not prefer. * - * @param bool|callable $inOut If callable it will create the group - * automatically and pass the query into the called function. For - * legacy operations use `true` to open brackets, `false` to close. - * @param string $op Conditional operator to use to join to the - * preceding condition. Default `AND`. + * @param bool|\Closure($this): void $inOut If callable it will create the group + * automatically and pass the query into the called function. For + * legacy operations use `true` to open brackets, `false` to close. + * @param string $op Conditional operator to use to join to the + * preceding condition. Default `AND`. * * @return $this * diff --git a/Editor.php b/Editor.php index b8c8b52..2795f8f 100644 --- a/Editor.php +++ b/Editor.php @@ -17,6 +17,7 @@ namespace DataTables; use DataTables; +use DataTables\Database\Query; use DataTables\Editor\Field; use DataTables\Editor\Join; @@ -561,9 +562,9 @@ public function leftJoinRemove($_ = null) * Add an event listener. The `Editor` class will trigger an number of * events that some action can be taken on. * - * @param string $name Event name - * @param callable $callback Callback function to execute when the event - * occurs + * @param string $name Event name + * @param callable($this, mixed, mixed, mixed, mixed, mixed): ?false $callback Callback function to execute when the event + * occurs * * @return $this */ @@ -859,9 +860,9 @@ public function validate(&$errors, $data) * and remove actions performed from the client-side. Multiple validators * can be added. * - * @param callable $_ Function to execute when validating the input data. - * It is passed three parameters: 1. The editor instance, 2. The action - * and 3. The values. + * @param callable($this, self::ACTION_*, array): ?string $_ Function to execute when validating the input data. + * It is passed three parameters: 1. The editor instance, 2. The action + * and 3. The values. * * @return ($_ is null ? callable : $this) The validator function. */ @@ -890,9 +891,9 @@ public function validator($_ = null) * undefined (since Editor expects the row to still be available, but the * condition removes it from the result set). * - * @param string|callable $key Single field name or a closure function - * @param string $value Single field value. - * @param string $op Condition operator: <, >, = etc + * @param string|\Closure(Query): void $key Single field name or a closure function + * @param string $value Single field value. + * @param string $op Condition operator: <, >, = etc * * @return ($key is null ? string[] : $this) Where condition array. */ @@ -2047,7 +2048,7 @@ private function _ssp_limit($query, $http) private function _get_where($query) { for ($i = 0; $i < count($this->_where); ++$i) { - if (is_callable($this->_where[$i])) { + if ($this->_where[$i] instanceof \Closure) { $this->_where[$i]($query); } else { $query->where( @@ -2220,7 +2221,7 @@ private function _insert_or_update_table($table, $values, $where = null) for ($j = 0, $jen = count($this->_where); $j < $jen; ++$j) { $cond = $this->_where[$j]; - if (!is_callable($cond)) { + if (!$cond instanceof \Closure) { // Make sure the value wasn't in the submitted data set, // otherwise we would be overwriting it if (!isset($set[$cond['key']])) { diff --git a/Editor/Field.php b/Editor/Field.php index 3a0f208..050c0f7 100644 --- a/Editor/Field.php +++ b/Editor/Field.php @@ -14,6 +14,8 @@ namespace DataTables\Editor; use DataTables; +use DataTables\Database; +use DataTables\Database\Query; use DataTables\Editor; use DataTables\HtmLawed\Htmlaw; @@ -228,13 +230,13 @@ public function get($_ = null) * Editor has a number of formatters available with the {@see Format} class * which can be used directly with this method. * - * @param callable|string $_ Value to set if using as a setter. Can be given as - * a closure function or a string with a reference to a function that will - * be called with call_user_func(). - * @param mixed $opts Variable that is passed through to the get formatting - * function - can be useful for passing through extra information such as - * date formatting string, or a required flag. The actual options available - * depend upon the formatter used. + * @param callable(mixed, array, array): string $_ Value to set if using as a setter. Can be given as + * a closure function or a string with a reference to a function that will + * be called with call_user_func(). + * @param mixed $opts Variable that is passed through to the get formatting + * function - can be useful for passing through extra information such as + * date formatting string, or a required flag. The actual options available + * depend upon the formatter used. * * @return ($_ is null ? callable|string : $this) The get formatter if no parameter is given. */ @@ -251,8 +253,8 @@ public function getFormatter($_ = null, $opts = null) * Get / set a get value. If given, then this value is used to send to the * client-side, regardless of what value is held by the database. * - * @param callable|string|number $_ Value to set, or no value to use as a - * getter + * @param \Closure(): mixed|string|number $_ Value to set, or no value to use as a + * getter * * @return ($_ is null ? callable|string : $this) Value if used as a getter. */ @@ -286,16 +288,16 @@ public function name($_ = null) * data, including pairs that require joins and where conditions, use a * closure to provide a query * - * @param string|callable $table Database table name to use to get the - * paired data from, or a closure function if providing a method - * @param string $value Table column name that contains the pair's - * value. Not used if the first parameter is given as a closure - * @param string $label Table column name that contains the pair's - * label. Not used if the first parameter is given as a closure - * @param callable $condition Function that will add `where` - * conditions to the query - * @param callable $format Function will render each label - * @param string $order SQL ordering + * @param string|callable(Database): (false|array) $table Database table name to use to get the + * paired data from, or a closure function if providing a method + * @param string $value Table column name that contains the pair's + * value. Not used if the first parameter is given as a closure + * @param string $label Table column name that contains the pair's + * label. Not used if the first parameter is given as a closure + * @param \Closure(Query): void $condition Function that will add `where` + * conditions to the query + * @param callable(array): string $format Function will render each label + * @param string $order SQL ordering * * @return ($table is null ? Options : $this) */ @@ -340,7 +342,7 @@ public function options($table = null, $value = null, $label = null, $condition /** * Get a list of values that can be used for the options list in SearchPanes. * - * @param SearchPaneOptions|callable $spInput SearchPaneOptions instance or a closure function if providing a method + * @param SearchPaneOptions|callable(Database, DataTables\Editor): (array|bool) $spInput SearchPaneOptions instance or a closure function if providing a method * * @return ($spInput is null ? SearchPaneOptions|null : $this) */ @@ -367,7 +369,7 @@ public function searchPaneOptions($spInput = null) /** * Get a list of values that can be used for the options list in SearchBuilder. * - * @param SearchBuilderOptions|callable $sbInput SearchBuilderOptions instance or a closure function if providing a method + * @param SearchBuilderOptions|callable(Database, DataTables\Editor): (Promise|bool) $sbInput SearchBuilderOptions instance or a closure function if providing a method * * @return ($sbInput is null ? SearchBuilderOptions|null : $this) */ @@ -434,13 +436,13 @@ public function set($_ = null) * Editor has a number of formatters available with the {@see Format} class * which can be used directly with this method. * - * @param callable|string $_ Value to set if using as a setter. Can be given as - * a closure function or a string with a reference to a function that will - * be called with call_user_func(). - * @param mixed $opts Variable that is passed through to the get formatting - * function - can be useful for passing through extra information such as - * date formatting string, or a required flag. The actual options available - * depend upon the formatter used. + * @param callable(mixed, array, array): string $_ Value to set if using as a setter. Can be given as + * a closure function or a string with a reference to a function that will + * be called with call_user_func(). + * @param mixed $opts Variable that is passed through to the get formatting + * function - can be useful for passing through extra information such as + * date formatting string, or a required flag. The actual options available + * depend upon the formatter used. * * @return ($_ is null ? callable|string : $this) The set formatter if no parameter is given. */ @@ -457,8 +459,8 @@ public function setFormatter($_ = null, $opts = null) * Get / set a set value. If given, then this value is used to write to the * database regardless of what data is sent from the client-side. * - * @param callable|string|number $_ Value to set, or no value to use as a - * getter + * @param \Closure(): mixed|string|number $_ Value to set, or no value to use as a + * getter * * @return ($_ is null ? callable|string : $this) Value if used as a getter. */ @@ -492,13 +494,13 @@ public function upload($_ = null) * Editor has a number of validation available with the {@see Validate} class * which can be used directly with this method. * - * @param callable|string $_ Value to set if using as the validation method. - * Can be given as a closure function or a string with a reference to a - * function that will be called with call_user_func(). - * @param mixed $opts Variable that is passed through to the validation - * function - can be useful for passing through extra information such as - * date formatting string, or a required flag. The actual options available - * depend upon the validation function used. + * @param callable(mixed, array, $this, array): (true|string)|string $_ Value to set if using as the validation method. + * Can be given as a closure function or a string with a reference to a + * function that will be called with call_user_func(). + * @param mixed $opts Variable that is passed through to the validation + * function - can be useful for passing through extra information such as + * date formatting string, or a required flag. The actual options available + * depend upon the validation function used. * * @return ($_ is null ? array[] : $this) The validation method if no parameter is given. */ @@ -531,8 +533,8 @@ public function validator($_ = null, $opts = null) * simply provide a closure function that returns the value given to the * function. This is _not_ recommended. * - * @param callable|false $xssFormatter XSS cleaner function, use `false` or - * `null` to disable XSS cleaning. + * @param callable(mixed): string|false $xssFormatter XSS cleaner function, use `false` or + * `null` to disable XSS cleaning. * * @return $this */ @@ -860,12 +862,12 @@ public function xssSafety($val) * Apply a formatter to data. The caller will decide what formatter to apply * (get or set). * - * @param mixed $val Value to be formatted - * @param array $data Full row data - * @param callable $formatter Formatting function to be called - * @param array $opts Array of options to be passed to the formatter + * @param mixed $val Value to be formatted + * @param array $data Full row data + * @param callable(mixed, array, array): string $formatter Formatting function to be called + * @param array $opts Array of options to be passed to the formatter * - * @return mixed Formatted value + * @return string Formatted value */ private function _format($val, $data, $formatter, $opts) { diff --git a/Editor/Join.php b/Editor/Join.php index b6a1a4e..51ed470 100644 --- a/Editor/Join.php +++ b/Editor/Join.php @@ -14,6 +14,7 @@ namespace DataTables\Editor; use DataTables; +use DataTables\Database\Query; use DataTables\Editor; /** @@ -404,9 +405,9 @@ public function type($_ = null) /** * Set a validator for the array of data (not on a field basis). * - * @param string $fieldName Name of the field that any error should be shown - * against on the client-side - * @param callable $fn Callback function for validation + * @param string $fieldName Name of the field that any error should be shown + * against on the client-side + * @param callable(Editor, string, string): ?string $fn Callback function for validation * * @return $this */ @@ -429,9 +430,9 @@ public function validator($fieldName, $fn) * * Simple case: `where( field, value, operator )` * * Complex: `where( fn )` * - * @param string|callable $key Single field name or a closure function - * @param string|string[] $value Single field value, or an array of values. - * @param string $op Condition operator: <, >, = etc + * @param string|\Closure(Query): void $key Single field name or a closure function + * @param string|string[] $value Single field value, or an array of values. + * @param string $op Condition operator: <, >, = etc * * @return ($key is null ? string[] : $this) Where condition array. */ @@ -809,7 +810,7 @@ public function validate(&$errors, $editor, $data, $action) private function _apply_where($query) { for ($i = 0; $i < count($this->_where); ++$i) { - if (is_callable($this->_where[$i])) { + if ($this->_where[$i] instanceof \Closure) { $this->_where[$i]($query); } else { $query->where( @@ -857,7 +858,7 @@ private function _insert($db, $parentId, $data) // Note that `whereSet` is now deprecated if ($this->_whereSet) { for ($i = 0, $ien = count($this->_where); $i < $ien; ++$i) { - if (!is_callable($this->_where[$i])) { + if (!$this->_where[$i] instanceof \Closure) { $stmt->set($this->_where[$i]['key'], $this->_where[$i]['value']); } } @@ -971,7 +972,7 @@ private function _update_row($db, $parentId, $data) // Is there any point in this? Is there any harm? // Note that `whereSet` is now deprecated if ($this->_whereSet) { - if (!is_callable($this->_where[$i])) { + if (!$this->_where[$i] instanceof \Closure) { $set[$this->_where[$i]['key']] = $this->_where[$i]['value']; } } diff --git a/Editor/Options.php b/Editor/Options.php index efcbc95..800bb0a 100644 --- a/Editor/Options.php +++ b/Editor/Options.php @@ -15,6 +15,7 @@ use DataTables; use DataTables\Database; +use DataTables\Database\Query; /** * The Options class provides a convenient method of specifying where Editor @@ -192,7 +193,7 @@ public function order($_ = null) * multiple database columns into a single string that is shown as the label * to the end user in the list of options. * - * @param callable|null $_ Function to set, null to get current value + * @param callable(array): string|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ @@ -231,7 +232,7 @@ public function value($_ = null) * Get / set the method to use for a WHERE condition if it is to be * applied to the query to get the options. * - * @param callable|null $_ Function to set, null to get current value + * @param \Closure(Query): void|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ diff --git a/Editor/SearchBuilderOptions.php b/Editor/SearchBuilderOptions.php index e49c2dc..4552b1b 100644 --- a/Editor/SearchBuilderOptions.php +++ b/Editor/SearchBuilderOptions.php @@ -14,6 +14,7 @@ namespace DataTables\Editor; use DataTables; +use DataTables\Database\Query; /** * The Options class provides a convenient method of specifying where Editor @@ -130,7 +131,7 @@ public function order($_ = null) * multiple database columns into a single string that is shown as the label * to the end user in the list of options. * - * @param callable|null $_ Function to set, null to get current value + * @param callable(string): string|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ @@ -169,7 +170,7 @@ public function value($_ = null) * Get / set the method to use for a WHERE condition if it is to be * applied to the query to get the options. * - * @param callable|null $_ Function to set, null to get current value + * @param \Closure(Query): void|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ @@ -211,7 +212,7 @@ public function leftJoin($table, $field1, $operator, $field2) private function _get_where($query) { for ($i = 0; $i < count($this->_where); ++$i) { - if (is_callable($this->_where[$i])) { + if ($this->_where[$i] instanceof \Closure) { $this->_where[$i]($query); } else { $query->where( diff --git a/Editor/SearchPaneOptions.php b/Editor/SearchPaneOptions.php index d728211..72270f8 100644 --- a/Editor/SearchPaneOptions.php +++ b/Editor/SearchPaneOptions.php @@ -14,6 +14,7 @@ namespace DataTables\Editor; use DataTables; +use DataTables\Database\Query; /** * The Options class provides a convenient method of specifying where Editor @@ -130,7 +131,7 @@ public function order($_ = null) * multiple database columns into a single string that is shown as the label * to the end user in the list of options. * - * @param callable|null $_ Function to set, null to get current value + * @param callable(string): string|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ @@ -169,7 +170,7 @@ public function value($_ = null) * Get / set the method to use for a WHERE condition if it is to be * applied to the query to get the options. * - * @param callable|null $_ Function to set, null to get current value + * @param \Closure(Query): void|null $_ Function to set, null to get current value * * @return ($_ is null ? callable : $this) */ @@ -211,7 +212,7 @@ public function leftJoin($table, $field1, $operator, $field2) private function _get_where($query) { for ($i = 0; $i < count($this->_where); ++$i) { - if (is_callable($this->_where[$i])) { + if ($this->_where[$i] instanceof \Closure) { $this->_where[$i]($query); } else { $query->where( diff --git a/Editor/Upload.php b/Editor/Upload.php index d619cb9..f55c7e2 100644 --- a/Editor/Upload.php +++ b/Editor/Upload.php @@ -14,6 +14,7 @@ namespace DataTables\Editor; use DataTables; +use DataTables\Database\Query; /** * Upload class for Editor. This class provides the ability to easily specify @@ -141,8 +142,8 @@ class Upload extends DataTables\Ext /** * Upload instance constructor. * - * @param string|callable $action Action to take on upload - this is applied - * directly to {@see Upload->action()}. + * @param string|\Closure(array, int): int $action Action to take on upload - this is applied + * directly to {@see Upload->action()}. */ public function __construct($action = null) { @@ -170,7 +171,7 @@ public function __construct($action = null) * typically involve writing it to the file system so it can be used * later. * - * @param string|callable $action Action to take - see description above. + * @param string|\Closure(array, int): int $action Action to take - see description above. * * @return $this */ @@ -211,19 +212,19 @@ public function allowedExtensions($extn, $error = 'This file type cannot be uplo * you wish to store relational information about your file on the database * (this is generally recommended). * - * @param string $table The name of the table where the file information - * should be stored - * @param string $pkey Primary key column name. The `Upload` class - * requires that the database table have a single primary key so each - * row can be uniquely identified. - * @param array $fields A list of the fields to be written to on upload. - * The property names are the database columns and the values can be - * defined by the constants of this class. The value can also be a - * string or a closure function if you wish to send custom information - * to the database. - * @param callable $format Formatting function that can change the data obtained - * from the database. Only gets a single parameter passed in - the - * database row for the file that is read. + * @param string $table The name of the table where the file information + * should be stored + * @param string $pkey Primary key column name. The `Upload` class + * requires that the database table have a single primary key so each + * row can be uniquely identified. + * @param array $fields A list of the fields to be written to on upload. + * The property names are the database columns and the values can be + * defined by the constants of this class. The value can also be a + * string or a closure function if you wish to send custom information + * to the database. + * @param callable(array&): void $format Formatting function that can change the data obtained + * from the database. Only gets a single parameter passed in - the + * database row for the file that is read. * * @return $this */ @@ -241,11 +242,11 @@ public function db($table, $pkey, $fields, $format = null) * Set a callback function that is used to remove files which no longer have * a reference in a source table. * - * @param callable $callback Function that will be executed on clean. It is - * given an array of information from the database about the orphaned - * rows, and can return true to indicate that the rows should be - * removed from the database. Any other return value (including none) - * will result in the records being retained. + * @param callable(array): bool $callback Function that will be executed on clean. It is + * given an array of information from the database about the orphaned + * rows, and can return true to indicate that the rows should be + * removed from the database. Any other return value (including none) + * will result in the records being retained. * * @return $this */ @@ -281,9 +282,9 @@ public function mode($m) * added by calling this method multiple times - they will be executed in * sequence when a file has been uploaded. * - * @param callable $fn Validation function. A PHP `$_FILES` parameter is - * passed in for the uploaded file and the return is either a string - * (validation failed and error message), or `null` (validation passed). + * @param callable(array): ?string $fn Validation function. A PHP `$_FILES` parameter is + * passed in for the uploaded file and the return is either a string + * (validation failed and error message), or `null` (validation passed). * * @return $this */ @@ -300,7 +301,7 @@ public function validator($fn) * will be passed in a single argument, the `Query` object, to which * conditions can be added. Multiple calls to this method can be made. * - * @param callable $fn Where function. + * @param \Closure(Query): void $fn Where function. * * @return $this */