1
0
mirror of https://github.com/vrana/adminer.git synced 2025-08-06 14:46:36 +02:00

Doc-comment: Improve array @param

This uses syntax from https://phpstan.org/writing-php-code/phpdoc-types#general-arrays.

int[] means an array of ints with arbitrary keys (usually strings)
list<string> means an array of strings with sequential integer keys starting at 0
list<string>[] means an arbitrary array of string lists
list<string[]> means list of arbitrary string arrays
string[][] means two dimensional array with arbitrary keys in both dimensions
array was left in the comments for https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
This commit is contained in:
Jakub Vrana
2025-03-25 14:31:27 +01:00
parent 26aa48122f
commit 2ee325183b
17 changed files with 97 additions and 97 deletions

View File

@@ -505,7 +505,7 @@ if (!defined('Adminer\DRIVER')) {
/** Get database collation /** Get database collation
* @param string * @param string
* @param array result of collations() * @param list<string>[] result of collations()
* @return string * @return string
*/ */
function db_collation($db, $collations) { function db_collation($db, $collations) {
@@ -535,7 +535,7 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Count tables in all databases /** Count tables in all databases
* @param array * @param list<string>
* @return int[] [$db => $tables] * @return int[] [$db => $tables]
*/ */
function count_tables($databases) { function count_tables($databases) {
@@ -752,7 +752,7 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Drop databases /** Drop databases
* @param array * @param list<string>
* @return bool * @return bool
*/ */
function drop_databases($databases) { function drop_databases($databases) {
@@ -809,7 +809,7 @@ if (!defined('Adminer\DRIVER')) {
* @param string "" to create * @param string "" to create
* @param string new name * @param string new name
* @param array of [$orig, $process_field, $after] * @param array of [$orig, $process_field, $after]
* @param array of strings * @param list<string>
* @param string * @param string
* @param string * @param string
* @param string * @param string
@@ -853,7 +853,7 @@ if (!defined('Adminer\DRIVER')) {
/** Run commands to alter indexes /** Run commands to alter indexes
* @param string escaped table name * @param string escaped table name
* @param array of ["index type", "name", ["column definition", ...]] or ["index type", "name", "DROP"] * @param array[] of ["index type", "name", ["column definition", ...]] or ["index type", "name", "DROP"]
* @return bool * @return bool
*/ */
function alter_indexes($table, $alter) { function alter_indexes($table, $alter) {
@@ -867,7 +867,7 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Run commands to truncate tables /** Run commands to truncate tables
* @param array * @param list<string>
* @return bool * @return bool
*/ */
function truncate_tables($tables) { function truncate_tables($tables) {
@@ -875,7 +875,7 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Drop views /** Drop views
* @param array * @param list<string>
* @return bool * @return bool
*/ */
function drop_views($views) { function drop_views($views) {
@@ -883,7 +883,7 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Drop tables /** Drop tables
* @param array * @param list<string>
* @return bool * @return bool
*/ */
function drop_tables($tables) { function drop_tables($tables) {
@@ -891,8 +891,8 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Move tables to other schema /** Move tables to other schema
* @param array * @param list<string>
* @param array * @param list<string>
* @param string * @param string
* @return bool * @return bool
*/ */
@@ -921,8 +921,8 @@ if (!defined('Adminer\DRIVER')) {
} }
/** Copy tables to other schema /** Copy tables to other schema
* @param array * @param list<string>
* @param array * @param list<string>
* @param string * @param string
* @return bool * @return bool
*/ */
@@ -1073,7 +1073,7 @@ if (!defined('Adminer\DRIVER')) {
/** Get approximate number of rows /** Get approximate number of rows
* @param array * @param array
* @param array * @param list<string>
* @return int or null if approximate number can't be retrieved * @return int or null if approximate number can't be retrieved
*/ */
function found_rows($table_status, $where) { function found_rows($table_status, $where) {

View File

@@ -467,11 +467,11 @@ if (isset($_GET["sqlite"])) {
/** Recreate table /** Recreate table
* @param string original name * @param string original name
* @param string new name * @param string new name
* @param array [process_field()], empty to preserve * @param list<list<string>> [process_field()], empty to preserve
* @param array [$original => idf_escape($new_column)], empty to preserve * @param string[] [$original => idf_escape($new_column)], empty to preserve
* @param string [format_foreign_key()], empty to preserve * @param string [format_foreign_key()], empty to preserve
* @param int set auto_increment to this value, 0 to preserve * @param int set auto_increment to this value, 0 to preserve
* @param array [[$type, $name, $columns]], empty to preserve * @param array[] [[$type, $name, $columns]], empty to preserve
* @param string CHECK constraint to drop * @param string CHECK constraint to drop
* @param string CHECK constraint to add * @param string CHECK constraint to add
* @return bool * @return bool

View File

@@ -227,8 +227,8 @@ class Adminer {
} }
/** Print backward keys for row /** Print backward keys for row
* @param array result of $this->backwardKeys() * @param array[] result of $this->backwardKeys()
* @param array * @param string[]
* @return null * @return null
*/ */
function backwardKeysPrint($backwardKeys, $row) { function backwardKeysPrint($backwardKeys, $row) {
@@ -277,8 +277,8 @@ class Adminer {
} }
/** Get descriptions of selected data /** Get descriptions of selected data
* @param array all data to print * @param list<string[]> all data to print
* @param array * @param array[]
* @return list<string[]> * @return list<string[]>
*/ */
function rowDescriptions($rows, $foreignKeys) { function rowDescriptions($rows, $foreignKeys) {
@@ -297,7 +297,7 @@ class Adminer {
* @param string HTML-escaped value to print * @param string HTML-escaped value to print
* @param string link to foreign key * @param string link to foreign key
* @param array single field returned from fields() * @param array single field returned from fields()
* @param array original value before applying editVal() and escaping * @param string original value before applying editVal() and escaping
* @return string * @return string
*/ */
function selectVal($val, $link, $field, $original) { function selectVal($val, $link, $field, $original) {
@@ -322,7 +322,7 @@ class Adminer {
} }
/** Print table structure in tabular format /** Print table structure in tabular format
* @param array data about individual fields * @param array[] data about individual fields
* @param array * @param array
* @return null * @return null
*/ */
@@ -354,7 +354,7 @@ class Adminer {
} }
/** Print list of indexes on table in tabular format /** Print list of indexes on table in tabular format
* @param array data about all indexes on a table * @param array[] data about all indexes on a table
* @return null * @return null
*/ */
function tableIndexesPrint($indexes) { function tableIndexesPrint($indexes) {
@@ -374,8 +374,8 @@ class Adminer {
} }
/** Print columns box in select /** Print columns box in select
* @param array result of selectColumnsProcess()[0] * @param list<string> result of selectColumnsProcess()[0]
* @param array selectable columns * @param string[] selectable columns
* @return null * @return null
*/ */
function selectColumnsPrint($select, $columns) { function selectColumnsPrint($select, $columns) {
@@ -401,9 +401,9 @@ class Adminer {
} }
/** Print search box in select /** Print search box in select
* @param array result of selectSearchProcess() * @param list<string> result of selectSearchProcess()
* @param array selectable columns * @param string[] selectable columns
* @param array * @param array[]
* @return null * @return null
*/ */
function selectSearchPrint($where, $columns, $indexes) { function selectSearchPrint($where, $columns, $indexes) {
@@ -437,9 +437,9 @@ class Adminer {
} }
/** Print order box in select /** Print order box in select
* @param array result of selectOrderProcess() * @param list<string> result of selectOrderProcess()
* @param array selectable columns * @param string[] selectable columns
* @param array * @param array[]
* @return null * @return null
*/ */
function selectOrderPrint($order, $columns, $indexes) { function selectOrderPrint($order, $columns, $indexes) {
@@ -481,7 +481,7 @@ class Adminer {
} }
/** Print action box in select /** Print action box in select
* @param array * @param array[]
* @return null * @return null
*/ */
function selectActionPrint($indexes) { function selectActionPrint($indexes) {
@@ -522,16 +522,16 @@ class Adminer {
} }
/** Print extra text in the end of a select form /** Print extra text in the end of a select form
* @param array fields holding e-mails * @param string[] fields holding e-mails
* @param array selectable columns * @param string[] selectable columns
* @return null * @return null
*/ */
function selectEmailPrint($emailFields, $columns) { function selectEmailPrint($emailFields, $columns) {
} }
/** Process columns box in select /** Process columns box in select
* @param array selectable columns * @param string[] selectable columns
* @param array * @param array[]
* @return list<list<string>> [[select_expressions], [group_expressions]] * @return list<list<string>> [[select_expressions], [group_expressions]]
*/ */
function selectColumnsProcess($columns, $indexes) { function selectColumnsProcess($columns, $indexes) {
@@ -550,8 +550,8 @@ class Adminer {
} }
/** Process search box in select /** Process search box in select
* @param array * @param array[]
* @param array * @param array[]
* @return list<string> expressions to join by AND * @return list<string> expressions to join by AND
*/ */
function selectSearchProcess($fields, $indexes) { function selectSearchProcess($fields, $indexes) {
@@ -604,8 +604,8 @@ class Adminer {
} }
/** Process order box in select /** Process order box in select
* @param array * @param array[]
* @param array * @param array[]
* @return list<string> expressions to join by comma * @return list<string> expressions to join by comma
*/ */
function selectOrderProcess($fields, $indexes) { function selectOrderProcess($fields, $indexes) {
@@ -635,8 +635,8 @@ class Adminer {
} }
/** Process extras in select form /** Process extras in select form
* @param array AND conditions * @param string[] AND conditions
* @param array * @param array[]
* @return bool true if processed, false to process other parts of form * @return bool true if processed, false to process other parts of form
*/ */
function selectEmailProcess($where, $foreignKeys) { function selectEmailProcess($where, $foreignKeys) {
@@ -644,10 +644,10 @@ class Adminer {
} }
/** Build SQL query used in select /** Build SQL query used in select
* @param array result of selectColumnsProcess()[0] * @param list<string> result of selectColumnsProcess()[0]
* @param array result of selectSearchProcess() * @param list<string> result of selectSearchProcess()
* @param array result of selectColumnsProcess()[1] * @param list<string> result of selectColumnsProcess()[1]
* @param array result of selectOrderProcess() * @param list<string> result of selectOrderProcess()
* @param int result of selectLimitProcess() * @param int result of selectLimitProcess()
* @param int index of page starting at zero * @param int index of page starting at zero
* @return string empty string to use default query * @return string empty string to use default query
@@ -689,7 +689,7 @@ class Adminer {
/** Print before edit form /** Print before edit form
* @param string * @param string
* @param array * @param array[]
* @param mixed * @param mixed
* @param bool * @param bool
* @return null * @return null
@@ -1051,7 +1051,7 @@ class Adminer {
} }
/** Set up syntax highlight for code and <textarea> /** Set up syntax highlight for code and <textarea>
* @param array result of table_status() * @param array[] result of table_status()
*/ */
function syntaxHighlighting($tables) { function syntaxHighlighting($tables) {
global $connection; global $connection;

View File

@@ -75,10 +75,10 @@ abstract class SqlDriver {
/** Select data from table /** Select data from table
* @param string * @param string
* @param array result of $adminer->selectColumnsProcess()[0] * @param list<string> result of $adminer->selectColumnsProcess()[0]
* @param array result of $adminer->selectSearchProcess() * @param list<string> result of $adminer->selectSearchProcess()
* @param array result of $adminer->selectColumnsProcess()[1] * @param list<string> result of $adminer->selectColumnsProcess()[1]
* @param array result of $adminer->selectOrderProcess() * @param list<string> result of $adminer->selectOrderProcess()
* @param int result of $adminer->selectLimitProcess() * @param int result of $adminer->selectLimitProcess()
* @param int index of page starting at zero * @param int index of page starting at zero
* @param bool whether to print the query * @param bool whether to print the query
@@ -118,7 +118,7 @@ abstract class SqlDriver {
/** Update data in table /** Update data in table
* @param string * @param string
* @param array escaped columns in keys, quoted data in values * @param string[] escaped columns in keys, quoted data in values
* @param string " WHERE ..." * @param string " WHERE ..."
* @param int 0 or 1 * @param int 0 or 1
* @param string * @param string
@@ -135,7 +135,7 @@ abstract class SqlDriver {
/** Insert data into table /** Insert data into table
* @param string * @param string
* @param array escaped columns in keys, quoted data in values * @param string[] escaped columns in keys, quoted data in values
* @return bool * @return bool
*/ */
function insert($table, $set) { function insert($table, $set) {
@@ -155,8 +155,8 @@ abstract class SqlDriver {
/** Insert or update data in table /** Insert or update data in table
* @param string * @param string
* @param array * @param list<string[]> of arrays with escaped columns in keys and quoted data in values
* @param array of arrays with escaped columns in keys and quoted data in values * @param int[] column names in keys
* @return bool * @return bool
*/ */
function insertUpdate($table, $rows, $primary) { function insertUpdate($table, $rows, $primary) {

View File

@@ -143,7 +143,7 @@ function textarea($name, $value, $rows = 10, $cols = 80) {
/** Generate HTML <select> or <input> if $options are empty /** Generate HTML <select> or <input> if $options are empty
* @param string * @param string
* @param array * @param string[]
* @param string * @param string
* @param string * @param string
* @param string * @param string
@@ -178,10 +178,10 @@ function json_row($key, $val = null) {
/** Print table columns for type edit /** Print table columns for type edit
* @param string * @param string
* @param array * @param list<string>[]
* @param array * @param array[]
* @param array returned by referencable_primary() * @param array[] returned by referencable_primary()
* @param array extra types to prepend * @param list<string> extra types to prepend
* @return null * @return null
*/ */
function edit_type($key, $field, $collations, $foreign_keys = array(), $extra_types = array()) { function edit_type($key, $field, $collations, $foreign_keys = array(), $extra_types = array()) {
@@ -317,10 +317,10 @@ function type_class($type) {
} }
/** Print table interior for fields editing /** Print table interior for fields editing
* @param array * @param array[]
* @param array * @param list<string>[]
* @param string TABLE or PROCEDURE * @param string TABLE or PROCEDURE
* @param array returned by referencable_primary() * @param array[] returned by referencable_primary()
* @return null * @return null
*/ */
function edit_fields($fields, $collations, $type = "TABLE", $foreign_keys = array()) { function edit_fields($fields, $collations, $type = "TABLE", $foreign_keys = array()) {
@@ -382,7 +382,7 @@ function edit_fields($fields, $collations, $type = "TABLE", $foreign_keys = arra
} }
/** Move fields up and down or add field /** Move fields up and down or add field
* @param array * @param array[]
* @return bool * @return bool
*/ */
function process_fields(&$fields) { function process_fields(&$fields) {
@@ -423,7 +423,7 @@ function process_fields(&$fields) {
} }
/** Callback used in routine() /** Callback used in routine()
* @param array * @param list<array>
* @return string * @return string
*/ */
function normalize_enum($match) { function normalize_enum($match) {
@@ -432,7 +432,7 @@ function normalize_enum($match) {
/** Issue grant or revoke commands /** Issue grant or revoke commands
* @param string GRANT or REVOKE * @param string GRANT or REVOKE
* @param array * @param list<string>
* @param string * @param string
* @param string * @param string
* @return bool * @return bool
@@ -502,7 +502,7 @@ function create_trigger($on, $row) {
/** Generate SQL query for creating routine /** Generate SQL query for creating routine
* @param string "PROCEDURE" or "FUNCTION" * @param string "PROCEDURE" or "FUNCTION"
* @param array result of routine() * @param string[] result of routine()
* @return string * @return string
*/ */
function create_routine($routine, $row) { function create_routine($routine, $row) {
@@ -587,7 +587,7 @@ function ini_bytes($ini) {
} }
/** Create link to database documentation /** Create link to database documentation
* @param array JUSH => $path * @param string[] JUSH => $path
* @param string HTML code * @param string HTML code
* @return string HTML code * @return string HTML code
*/ */

View File

@@ -81,7 +81,7 @@ function number_type() {
} }
/** Disable magic_quotes_gpc /** Disable magic_quotes_gpc
* @param array e.g. (&$_GET, &$_POST, &$_COOKIE) * @param list<array> e.g. (&$_GET, &$_POST, &$_COOKIE)
* @param bool whether to leave values as is * @param bool whether to leave values as is
* @return null modified in place * @return null modified in place
*/ */
@@ -261,8 +261,8 @@ function get_rows($query, $connection2 = null, $error = "<p class='error'>") {
} }
/** Find unique identifier of a row /** Find unique identifier of a row
* @param array * @param string[]
* @param array result of indexes() * @param array[] result of indexes()
* @return string[] or null if there is no unique identifier * @return string[] or null if there is no unique identifier
*/ */
function unique_array($row, $indexes) { function unique_array($row, $indexes) {
@@ -293,7 +293,7 @@ function escape_key($key) {
/** Create SQL condition from parsed query string /** Create SQL condition from parsed query string
* @param array parsed query string * @param array parsed query string
* @param array * @param array[]
* @return string * @return string
*/ */
function where($where, $fields = array()) { function where($where, $fields = array()) {
@@ -321,7 +321,7 @@ function where($where, $fields = array()) {
/** Create SQL condition from query string /** Create SQL condition from query string
* @param string * @param string
* @param array * @param array[]
* @return string * @return string
*/ */
function where_check($val, $fields = array()) { function where_check($val, $fields = array()) {
@@ -342,9 +342,9 @@ function where_link($i, $column, $value, $operator = "=") {
} }
/** Get select clause for convertible fields /** Get select clause for convertible fields
* @param array * @param string[]
* @param array * @param array[]
* @param array * @param list<string>
* @return string * @return string
*/ */
function convert_fields($columns, $fields, $select = array()) { function convert_fields($columns, $fields, $select = array()) {
@@ -551,7 +551,7 @@ function queries($query) {
/** Apply command to all array items /** Apply command to all array items
* @param string * @param string
* @param array * @param list<string>
* @param callback * @param callback
* @return bool * @return bool
*/ */
@@ -770,7 +770,7 @@ function dump_headers($identifier, $multi_table = false) {
} }
/** Print CSV row /** Print CSV row
* @param array * @param string[]
* @return null * @return null
*/ */
function dump_csv($row) { function dump_csv($row) {
@@ -962,9 +962,9 @@ function is_shortable($field) {
/** Get query to compute number of found rows /** Get query to compute number of found rows
* @param string * @param string
* @param array * @param list<string>
* @param bool * @param bool
* @param array * @param list<string>
* @return string * @return string
*/ */
function count_rows($table, $where, $is_group, $group) { function count_rows($table, $where, $is_group, $group) {

View File

@@ -87,7 +87,7 @@ function checkbox($name, $value, $checked, $label = "", $onclick = "", $class =
} }
/** Generate list of HTML options /** Generate list of HTML options
* @param array array of strings or arrays (creates optgroup) * @param string[]|string[][] array of strings or arrays (creates optgroup)
* @param mixed * @param mixed
* @param bool always use array keys for value="", otherwise only string keys are used * @param bool always use array keys for value="", otherwise only string keys are used
* @return string * @return string
@@ -116,7 +116,7 @@ function optionlist($options, $selected = null, $use_keys = false) {
/** Generate HTML <select> /** Generate HTML <select>
* @param string * @param string
* @param array * @param string[]
* @param string * @param string
* @param string * @param string
* @param string * @param string
@@ -132,7 +132,7 @@ function html_select($name, $options, $value = "", $onchange = "", $labelled_by
/** Generate HTML radio list /** Generate HTML radio list
* @param string * @param string
* @param array * @param string[]
* @param string * @param string
* @return string * @return string
*/ */
@@ -198,7 +198,7 @@ function pagination($page, $current) {
/** Print hidden fields /** Print hidden fields
* @param array * @param array
* @param array * @param list<string>
* @param string * @param string
* @return bool * @return bool
*/ */
@@ -426,7 +426,7 @@ function on_help($command, $side = 0) {
/** Print edit data form /** Print edit data form
* @param string * @param string
* @param array * @param array[]
* @param mixed * @param mixed
* @param bool * @param bool
* @return null * @return null

View File

@@ -5,7 +5,7 @@ class Plugins extends Adminer {
public $plugins; ///< @var protected(set) array public $plugins; ///< @var protected(set) array
/** Register plugins /** Register plugins
* @param array object instances or null to autoload plugins from adminer-plugins/ * @param list<object> object instances or null to autoload plugins from adminer-plugins/
*/ */
function __construct($plugins) { function __construct($plugins) {
if ($plugins === null) { if ($plugins === null) {

View File

@@ -15,7 +15,7 @@ function email_header($header) {
* @param string * @param string
* @param string * @param string
* @param string * @param string
* @param array * @param array[]
* @return bool * @return bool
*/ */
function send_mail($email, $subject, $message, $from = "", $files = array()) { function send_mail($email, $subject, $message, $from = "", $files = array()) {

View File

@@ -10,7 +10,7 @@ class AdminerDatabaseHide {
protected $disabled; protected $disabled;
/** /**
* @param array case insensitive database names in values * @param list<string> case insensitive database names in values
*/ */
function __construct($disabled) { function __construct($disabled) {
$this->disabled = array_map('strtolower', $disabled); $this->disabled = array_map('strtolower', $disabled);

View File

@@ -10,7 +10,7 @@ class AdminerDesigns {
protected $designs; protected $designs;
/** /**
* @param array URL in key, name in value * @param list<string> URL in key, name in value
*/ */
function __construct($designs) { function __construct($designs) {
$this->designs = $designs; $this->designs = $designs;

View File

@@ -10,8 +10,8 @@ class AdminerLoginIp {
protected $ips, $forwarded_for; protected $ips, $forwarded_for;
/** Set allowed IP addresses /** Set allowed IP addresses
* @param array IP address prefixes * @param list<string> IP address prefixes
* @param array X-Forwarded-For prefixes if IP address matches, empty array means anything * @param list<string> X-Forwarded-For prefixes if IP address matches, empty array means anything
*/ */
function __construct($ips, $forwarded_for = array()) { function __construct($ips, $forwarded_for = array()) {
$this->ips = $ips; $this->ips = $ips;

View File

@@ -10,7 +10,7 @@ class AdminerLoginServers {
protected $servers; protected $servers;
/** Set supported servers /** Set supported servers
* @param array [$description => ["server" => , "driver" => "server|pgsql|sqlite|..."]] * @param array[] [$description => ["server" => , "driver" => "server|pgsql|sqlite|..."]]
*/ */
function __construct($servers) { function __construct($servers) {
$this->servers = $servers; $this->servers = $servers;

View File

@@ -10,7 +10,7 @@ class AdminerMasterSlave {
private $masters = array(); private $masters = array();
/** /**
* @param array [$slave => $master] * @param string[] [$slave => $master]
*/ */
function __construct($masters) { function __construct($masters) {
$this->masters = $masters; $this->masters = $masters;

View File

@@ -9,7 +9,7 @@
class AdminerTableIndexesStructure { class AdminerTableIndexesStructure {
/** Print table structure in tabular format /** Print table structure in tabular format
* @Param array data about all indexes on a table * @param array[] data about all indexes on a table
* @return bool * @return bool
*/ */
function tableIndexesPrint($indexes) { function tableIndexesPrint($indexes) {

View File

@@ -9,7 +9,7 @@
class AdminerTableStructure { class AdminerTableStructure {
/** Print table structure in tabular format /** Print table structure in tabular format
* @param array data about individual fields * @param array[] data about individual fields
* @return bool * @return bool
*/ */
function tableStructurePrint($fields, $tableStatus = null) { function tableStructurePrint($fields, $tableStatus = null) {

View File

@@ -11,7 +11,7 @@ class AdminerWymeditor {
protected $scripts, $options; protected $scripts, $options;
/** /**
* @param array * @param list<string>
* @param string in format "skin: 'custom', preInit: function () { }" * @param string in format "skin: 'custom', preInit: function () { }"
*/ */
function __construct($scripts = array("jquery/jquery.js", "wymeditor/jquery.wymeditor.min.js"), $options = "") { function __construct($scripts = array("jquery/jquery.js", "wymeditor/jquery.wymeditor.min.js"), $options = "") {