Skip to content

Generate mysqli methodsynopses based on stubs #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Generate mysqli methodsynopses based on stubs #301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 34 additions & 37 deletions reference/mysqli/mysqli/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,31 +13,31 @@
<para>&style.oop;</para>
<constructorsynopsis>
<modifier>public</modifier> <methodname>mysqli::__construct</methodname>
<methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>ini_get("mysqli.default_host")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>ini_get("mysqli.default_user")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>ini_get("mysqli.default_port")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>socket</parameter><initializer>ini_get("mysqli.default_socket")</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default is an empty string or whatever is configured in INI

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not true. php/php-src@9cf6a54 fixed the default value handling by making these params nullable with a null default value.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nikic Could you share your opinion? I haven't noticed any change to the default values between PHP 7 and 8. Whether I pass NULL or an empty string the behaviour is the same. For mysqli_connect(), mysqli::connect(), mysqli_real_connect() and mysqli::real_connect() the first 3 parameters are as follows:

  • Host: The default value is taken from INI file and if not present then the default is "localhost"
  • Username: The default value is taken from INI file and if not present then the default is ""
  • Password: The default value is taken from INI file and if not present then the default is ""

For mysqli constructor, the first argument is a little magical. If nothing is provided, not even NULL or empty string, then it falls back to mysqli_init().

This is also inline with what the MySQL doc says https://dev.mysql.com/doc/c-api/8.0/en/mysql-real-connect.html

What change have you made to these functions recently?

<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
</constructorsynopsis>
<methodsynopsis role="oop">
<modifier>public</modifier> <type>void</type><methodname>mysqli::connect</methodname>
<methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>ini_get("mysqli.default_host")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>ini_get("mysqli.default_user")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>ini_get("mysqli.default_port")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>socket</parameter><initializer>ini_get("mysqli.default_socket")</initializer></methodparam>
<modifier>public</modifier> <type class="union"><type>mysqli</type><type>null</type><type>false</type></type><methodname>mysqli::connect</methodname>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<type class="union"><type>mysqli</type><type>false</type></type><methodname>mysqli_connect</methodname>
<methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>ini_get("mysqli.default_host")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>ini_get("mysqli.default_user")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>ini_get("mysqli.default_port")</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>socket</parameter><initializer>ini_get("mysqli.default_socket")</initializer></methodparam>
<methodsynopsis role="procedural">
<type class="union"><type>mysqli</type><type>null</type><type>false</type></type><methodname>mysqli_connect</methodname>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Opens a connection to the MySQL Server.
Expand All @@ -49,12 +49,12 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>host</parameter></term>
<term><parameter>hostname</parameter></term>
<listitem>
<para>
Can be either a host name or an IP address. The local host is
assumed when passing the &null; value or the string "localhost" to this parameter.
When possible, pipes will be used instead of the TCP/IP protocol.
Can be either a host name or an IP address. The local host is
assumed when passing the &null; value or the string "localhost" to this parameter.
When possible, pipes will be used instead of the TCP/IP protocol.
The TCP/IP protocol is used if a host name and port number are provided together e.g. <literal>localhost:3308</literal>.
</para>
<para>
Expand All @@ -73,7 +73,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>passwd</parameter></term>
<term><parameter>password</parameter></term>
<listitem>
<para>
If not provided or &null;, the MySQL server will attempt to authenticate
Expand All @@ -84,7 +84,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dbname</parameter></term>
<term><parameter>database</parameter></term>
<listitem>
<para>
If provided will specify the default database to be used when
Expand All @@ -111,7 +111,7 @@
Specifying the <parameter>socket</parameter> parameter will not
explicitly determine the type of connection to be used when
connecting to the MySQL server. How the connection is made to the
MySQL database is determined by the <parameter>host</parameter>
MySQL database is determined by the <parameter>hostname</parameter>
parameter.
</para>
</note>
Expand All @@ -124,7 +124,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<methodname>mysqli::__construct</methodname> always returns an object which represents the connection to a MySQL Server,
<methodname>mysqli::__construct</methodname> always returns an object which represents the connection to a MySQL Server,
regardless of it being successful or not.
</para>
<para>
Expand All @@ -139,7 +139,7 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
If <constant>MYSQLI_REPORT_STRICT</constant> is enabled and the attempt to connect
If <constant>MYSQLI_REPORT_STRICT</constant> is enabled and the attempt to connect
to the requested database fails, a <classname>mysqli_sql_exception</classname> is thrown.
</para>
</refsect1>
Expand Down Expand Up @@ -254,10 +254,9 @@ if (mysqli_errno($mysqli)) {
&mysqli.charset.note;
<note>
<para>
&style.oop; only: If the connection fails, an object is still returned. To check
whether the connection failed, use either the
<function>mysqli_connect_error</function> function or the <link
linkend="mysqli.connect-error">mysqli->connect_error</link> property as in
&style.oop; only: If the connection fails, an object is still returned. To check
whether the connection failed, use either the
<function>mysqli_connect_error</function> function or the <link linkend="mysqli.connect-error">mysqli-&gt;connect_error</link> property as in
the preceding examples.
</para>
</note>
Expand All @@ -275,8 +274,7 @@ if (mysqli_errno($mysqli)) {
</note>
<note>
<para>
Error "Can't create TCP/IP socket (10106)" usually means that the <link
linkend="ini.variables-order">variables_order</link> configure directive
Error "Can't create TCP/IP socket (10106)" usually means that the <link linkend="ini.variables-order">variables_order</link> configure directive
doesn't contain character <literal>E</literal>. On Windows, if the
environment is not copied the <literal>SYSTEMROOT</literal> environment
variable won't be available and PHP will have problems loading Winsock.
Expand All @@ -298,7 +296,6 @@ if (mysqli_errno($mysqli)) {
</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
7 changes: 3 additions & 4 deletions reference/mysqli/mysqli/init.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
<methodsynopsis role="oop">
<modifier>public</modifier> <type>mysqli</type><methodname>mysqli::init</methodname>
<methodsynopsis>
<modifier>public</modifier> <type class="union"><type>mysqli</type><type>false</type></type><methodname>mysqli::init</methodname>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This method does not return anything. It's void. Although recent discussion indicates that it might be possible for this method to return false under some exotic circumstances. See php/php-src#6540

It definitely does not return a mysqli object. Bear in mind that this is not the same as mysqli_init(). The method works differently than the function.

<void/>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<type>mysqli</type><methodname>mysqli_init</methodname>
<type class="union"><type>mysqli</type><type>false</type></type><methodname>mysqli_init</methodname>
<void/>
</methodsynopsis>
<para>
Expand Down Expand Up @@ -59,7 +59,6 @@
</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
41 changes: 20 additions & 21 deletions reference/mysqli/mysqli/real-connect.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,25 @@
<para>&style.oop;</para>
<methodsynopsis role="oop">
<modifier>public</modifier> <type>bool</type><methodname>mysqli::real_connect</methodname>
<methodparam choice="opt"><type>string</type><parameter>host</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as with mysqli::connect() the first three parameters cannot be null. The default for the first one is localhost or whatever is stored in INI. The other two have empty string as default or whatever is stored in INI

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you looking at the right branch? They are definitely nullable.

But again, every change in this PR is autogenerated from the canonical source of truth (mysqli.stub.php), so I'd appreciate if you could review the stubs first, so that I can update this PR after the issues are addressed "upstream".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify, I meant that even though all arguments are nullable (in the sense than you can provide all NULL arguments) the default values are not NULL. Even if you pass NULL as the hostname then the value will be a string 'localhost'.

Copy link
Member Author

@kocsismate kocsismate Jan 4, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but from an end-user perspective, it doesn't matter what the implementation does with the default value. Sure, in this particular case, "localhost" could have been defined as default, but it can't be changed anymore, and null is also ok.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let's make the signatures for connect methods as you're suggesting. I will have a think about how to improve these manual pages so that we don't lose this crucial information.

<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<methodsynopsis role="procedural">
<type>bool</type><methodname>mysqli_real_connect</methodname>
<methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>host</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>socket</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
Establish a connection to a MySQL database engine.
Expand Down Expand Up @@ -65,7 +65,7 @@
<variablelist>
&mysqli.link.description;
<varlistentry>
<term><parameter>host</parameter></term>
<term><parameter>hostname</parameter></term>
<listitem>
<para>
Can be either a host name or an IP address. Passing the &null; value
Expand All @@ -84,7 +84,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>passwd</parameter></term>
<term><parameter>password</parameter></term>
<listitem>
<para>
If provided or &null;, the MySQL server will attempt to authenticate
Expand All @@ -95,7 +95,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dbname</parameter></term>
<term><parameter>database</parameter></term>
<listitem>
<para>
If provided will specify the default database to be used when
Expand All @@ -122,7 +122,7 @@
Specifying the <parameter>socket</parameter> parameter will not
explicitly determine the type of connection to be used when
connecting to the MySQL server. How the connection is made to the
MySQL database is determined by the <parameter>host</parameter>
MySQL database is determined by the <parameter>hostname</parameter>
parameter.
</para>
</note>
Expand Down Expand Up @@ -320,7 +320,6 @@ Success... MySQL host info: localhost via TCP/IP
</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
9 changes: 3 additions & 6 deletions reference/mysqli/mysqli_stmt/bind-param.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,13 @@
<methodsynopsis role="oop">
<modifier>public</modifier> <type>bool</type><methodname>mysqli_stmt::bind_param</methodname>
<methodparam><type>string</type><parameter>types</parameter></methodparam>
<methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this removed? The second argument is mandatory. The variadic arguments that follow are only optional.

<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<methodsynopsis role="procedural">
<type>bool</type><methodname>mysqli_stmt_bind_param</methodname>
<methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam>
<methodparam><type>mysqli_stmt</type><parameter>statement</parameter></methodparam>
<methodparam><type>string</type><parameter>types</parameter></methodparam>
<methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
Expand Down Expand Up @@ -90,7 +88,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>var</parameter></term>
<term><parameter>vars</parameter></term>
<term><parameter>vars</parameter></term>
<listitem>
<para>
Expand Down Expand Up @@ -215,7 +213,6 @@ mysqli_close($link);
</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down
11 changes: 4 additions & 7 deletions reference/mysqli/mysqli_stmt/bind-result.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,12 @@
<para>&style.oop;</para>
<methodsynopsis role="oop">
<modifier>public</modifier> <type>bool</type><methodname>mysqli_stmt::bind_result</methodname>
<methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<methodsynopsis role="procedural">
<type>bool</type><methodname>mysqli_stmt_bind_result</methodname>
<methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam>
<methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
<methodparam><type>mysqli_stmt</type><parameter>statement</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
Expand All @@ -28,7 +26,7 @@
<para>
When <function>mysqli_stmt_fetch</function> is called to fetch data, the
MySQL client/server protocol places the data for the bound columns into
the specified variables <parameter>var</parameter>/<parameter>vars</parameter>.
the specified variables <parameter>vars</parameter>/<parameter>vars</parameter>.
</para>
<note>
<para>
Expand All @@ -52,7 +50,7 @@
<variablelist>
&mysqli.stmt.description;
<varlistentry>
<term><parameter>var</parameter></term>
<term><parameter>vars</parameter></term>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as with bind_param. The first variable is mandatory, the rest is optional.

<listitem>
<para>
The first variable to be bound.
Expand Down Expand Up @@ -179,7 +177,6 @@ AND Andorra
</refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Expand Down