From f84144e0b6efe908122946f98f2c517fecf39b37 Mon Sep 17 00:00:00 2001 From: Kamil Tekiela Date: Thu, 29 Sep 2022 23:31:07 +0100 Subject: [PATCH 1/3] Document mysqli_execute_query --- reference/mysqli/mysqli/execute-query.xml | 212 ++++++++++++++++++++++ reference/mysqli/versions.xml | 2 + 2 files changed, 214 insertions(+) create mode 100644 reference/mysqli/mysqli/execute-query.xml diff --git a/reference/mysqli/mysqli/execute-query.xml b/reference/mysqli/mysqli/execute-query.xml new file mode 100644 index 000000000000..3a0eb7dcf89d --- /dev/null +++ b/reference/mysqli/mysqli/execute-query.xml @@ -0,0 +1,212 @@ + + + + + mysqli::execute_query + mysqli_execute_query + Prepares, binds parameters, and executes SQL statement + + + + &reftitle.description; + &style.oop; + + public mysqli_resultboolmysqli::execute_query + stringquery + arraynullparams&null; + + &style.procedural; + + mysqli_resultboolmysqli_execute_query + mysqlimysql + stringquery + arraynullparams&null; + + + Prepares the SQL query, binds parameters, and executes it. + The mysqli::execute_query method is a shortcut for + mysqli::prepare, + mysqli_stmt::bind_param, + mysqli_stmt::execute, + and mysqli_stmt::get_result. + + + The statement template can contain zero or more question mark + (?) parameter markers⁠—also called placeholders. + The parameter values must be provided as an &array; using + params parameter. + + + A prepared statement is created under the hood but it's never exposed + outside of the function. It's impossible to access properties of the + statement as one would do with the mysqli_stmt object. + Due to this limitation, the status information is copied to the + mysqli object and is available using its methods, e.g. + mysqli_affected_rows or mysqli_error. + + + + In the case where you pass a statement to + mysqli_execute_query that is longer than + max_allowed_packet of the server, the returned + error codes are different depending on whether you are using Windows or Linux. + The behavior is as follows: + + + + + On Linux returns an error code of 1153. + The error message means got a packet bigger than + max_allowed_packet bytes. + + + + + On Windows returns an error code 2006. + This error message means server has gone away. + + + + + + + + &reftitle.parameters; + + + &mysqli.link.description; + + query + + + The query, as a string. It must consist of a single SQL statement. + + + The SQL statement may contain zero or more parameter markers + represented by question mark (?) characters + at the appropriate positions. + + + + + The markers are legal only in certain places in SQL statements. + For example, they are permitted in the VALUES() + list of an INSERT statement (to specify column + values for a row), or in a comparison with a column in a + WHERE clause to specify a comparison value. + + + However, they are not permitted for identifiers (such as table or + column names), or to specify both + operands of a binary operator such as the = equal + sign. The latter restriction is necessary because it would be + impossible to determine the parameter type. In general, parameters are + legal only in Data Manipulation Language (DML) statements, and not in + Data Definition Language (DDL) statements. + + + + + + params + + + An optional list &array; with as many elements as there are bound parameters in the SQL statement being executed. Each value is treated as a &string;. + + + + + + + + + &reftitle.returnvalues; + + Returns &false; on failure. For successful queries which produce a result + set, such as SELECT, SHOW, DESCRIBE or + EXPLAIN, returns + a mysqli_result object. For other successful queries, + returns &true;. + + + + + &reftitle.examples; + + <methodname>mysqli::execute_query</methodname> example + &style.oop; + +execute_query($query, ['DEU']); +foreach ($result as $row) { + printf("%s (%s)\n", $row["Name"], $row["District"]); +} +]]> + + &style.procedural; + + + + &examples.outputs.similar; + + + + + + + + &reftitle.seealso; + + + mysqli_prepare + mysqli_stmt_execute + mysqli_stmt_bind_param + mysqli_stmt_get_result + + + + + + diff --git a/reference/mysqli/versions.xml b/reference/mysqli/versions.xml index 318754f92dfb..cba3cd7907cb 100644 --- a/reference/mysqli/versions.xml +++ b/reference/mysqli/versions.xml @@ -24,6 +24,7 @@ + @@ -135,6 +136,7 @@ + From 72a52bc5136af527baa1f55be4c0963dee2170cf Mon Sep 17 00:00:00 2001 From: Kamil Tekiela Date: Wed, 12 Oct 2022 14:42:06 +0100 Subject: [PATCH 2/3] Drop inaccurate and confusing part copied from MySQL docs --- reference/mysqli/mysqli/execute-query.xml | 9 +-------- reference/mysqli/mysqli/prepare.xml | 9 +-------- reference/mysqli/mysqli_stmt/prepare.xml | 9 +-------- 3 files changed, 3 insertions(+), 24 deletions(-) diff --git a/reference/mysqli/mysqli/execute-query.xml b/reference/mysqli/mysqli/execute-query.xml index 3a0eb7dcf89d..1e48cfc1c288 100644 --- a/reference/mysqli/mysqli/execute-query.xml +++ b/reference/mysqli/mysqli/execute-query.xml @@ -94,15 +94,8 @@ list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. - - However, they are not permitted for identifiers (such as table or - column names), or to specify both - operands of a binary operator such as the = equal - sign. The latter restriction is necessary because it would be - impossible to determine the parameter type. In general, parameters are - legal only in Data Manipulation Language (DML) statements, and not in - Data Definition Language (DDL) statements. + column names). diff --git a/reference/mysqli/mysqli/prepare.xml b/reference/mysqli/mysqli/prepare.xml index 3803667fd137..ceda8a166e57 100644 --- a/reference/mysqli/mysqli/prepare.xml +++ b/reference/mysqli/mysqli/prepare.xml @@ -56,15 +56,8 @@ list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. - - However, they are not permitted for identifiers (such as table or - column names), or to specify both - operands of a binary operator such as the = equal - sign. The latter restriction is necessary because it would be - impossible to determine the parameter type. In general, parameters are - legal only in Data Manipulation Language (DML) statements, and not in - Data Definition Language (DDL) statements. + column names). diff --git a/reference/mysqli/mysqli_stmt/prepare.xml b/reference/mysqli/mysqli_stmt/prepare.xml index 5fc0343083a5..93e7c80b58a8 100644 --- a/reference/mysqli/mysqli_stmt/prepare.xml +++ b/reference/mysqli/mysqli_stmt/prepare.xml @@ -88,15 +88,8 @@ list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. - - However, they are not permitted for identifiers (such as table or - column names), or to specify both - operands of a binary operator such as the = equal - sign. The latter restriction is necessary because it would be - impossible to determine the parameter type. In general, parameters are - legal only in Data Manipulation Language (DML) statements, and not in - Data Definition Language (DDL) statements. + column names). From fe3703e02bbe8520dc5234c31892b2c0352c15ea Mon Sep 17 00:00:00 2001 From: Kamil Tekiela Date: Wed, 12 Oct 2022 14:31:32 +0100 Subject: [PATCH 3/3] Changed 'you' to formal style Co-authored-by: Christoph M. Becker --- reference/mysqli/mysqli/execute-query.xml | 4 ++-- reference/mysqli/mysqli/query.xml | 2 +- reference/mysqli/mysqli_stmt/prepare.xml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/mysqli/mysqli/execute-query.xml b/reference/mysqli/mysqli/execute-query.xml index 1e48cfc1c288..ec906774371a 100644 --- a/reference/mysqli/mysqli/execute-query.xml +++ b/reference/mysqli/mysqli/execute-query.xml @@ -46,10 +46,10 @@ - In the case where you pass a statement to + In the case where a statement is passed to mysqli_execute_query that is longer than max_allowed_packet of the server, the returned - error codes are different depending on whether you are using Windows or Linux. + error codes are different depending on the operating system. The behavior is as follows: diff --git a/reference/mysqli/mysqli/query.xml b/reference/mysqli/mysqli/query.xml index e24054457618..65e0031eb032 100644 --- a/reference/mysqli/mysqli/query.xml +++ b/reference/mysqli/mysqli/query.xml @@ -34,7 +34,7 @@ - In the case where you pass a statement to + In the case where a statement is passed to mysqli_query that is longer than max_allowed_packet of the server, the returned error codes are different depending on whether you are using MySQL diff --git a/reference/mysqli/mysqli_stmt/prepare.xml b/reference/mysqli/mysqli_stmt/prepare.xml index 93e7c80b58a8..139ea3309228 100644 --- a/reference/mysqli/mysqli_stmt/prepare.xml +++ b/reference/mysqli/mysqli_stmt/prepare.xml @@ -32,7 +32,7 @@ - In the case where you pass a statement to + In the case where a statement is passed to mysqli_stmt_prepare that is longer than max_allowed_packet of the server, the returned error codes are different depending on whether you are using MySQL