Fix #2242 : Wrong parameters names for mysqli::real_connect (#2462)

php · May 8, 2023 · 2d77c9f · 2d77c9f
1 parent f781803
commit 2d77c9f
Show file tree

Hide file tree

Showing 2 changed files with 111 additions and 63 deletions.
diff --git a/reference/mysqli/mysqli/construct.xml b/reference/mysqli/mysqli/construct.xml
@@ -13,31 +13,31 @@
   <para>&style.oop;</para>
   <constructorsynopsis role="mysqli">
    <modifier>public</modifier> <methodname>mysqli::__construct</methodname>
-   <methodparam choice="opt"><type>string</type><parameter>hostname</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>password</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>database</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>
+   <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="mysqli">
-   <modifier>public</modifier> <type>void</type><methodname>mysqli::connect</methodname>
-   <methodparam choice="opt"><type>string</type><parameter>hostname</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>password</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>database</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>bool</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>hostname</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>password</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>database</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>
+   <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.
@@ -52,9 +52,9 @@
      <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. When passing &null;, the value is retrieved from
+       <link linkend="ini.mysqli.default-host">mysqli.default_host</link>.
+       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>
@@ -68,43 +68,43 @@
      <term><parameter>username</parameter></term>
      <listitem>
       <para>
-       The MySQL user name.
+       The MySQL username or &null; to assume the username based on the
+       <link linkend="ini.mysqli.default-user">mysqli.default_user</link> ini option.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>password</parameter></term>
      <listitem>
       <para>
-       If not provided or &null;, the MySQL server will attempt to authenticate
-       the user against those user records which have no password only. This
-       allows one username to be used with different permissions (depending
-       on if a password is provided or not).
+       The MySQL password or &null; to assume the password based on the
+       <link linkend="ini.mysqli.default-pw">mysqli.default_pw</link> ini option.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>database</parameter></term>
      <listitem>
       <para>
-       If provided will specify the default database to be used when
-       performing queries.
+       The default database to be used when performing queries or &null;.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>port</parameter></term>
      <listitem>
       <para>
-       Specifies the port number to attempt to connect to the MySQL server.
+       The port number to attempt to connect to the MySQL server or &null; to assume the port based on the
+       <link linkend="ini.mysqli.default-port">mysqli.default_port</link> ini option.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>socket</parameter></term>
      <listitem>
       <para>
-       Specifies the socket or named pipe that should be used.
+       The socket or named pipe that should be used or &null; to assume the socket based on the
+       <link linkend="ini.mysqli.default-socket">mysqli.default_socket</link> ini option.
       </para>
       <note>
        <para>
@@ -141,6 +141,30 @@
   &mysqli.conditionalexception;
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        All parameters are now nullable.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>

diff --git a/reference/mysqli/mysqli/real-connect.xml b/reference/mysqli/mysqli/real-connect.xml
@@ -12,25 +12,25 @@
   <para>&style.oop;</para>
   <methodsynopsis role="mysqli">
    <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>
+   <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>
    <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.
@@ -65,64 +65,64 @@
    <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
-       or the string "localhost" to this parameter, the local host is
-       assumed. When possible, pipes will be used instead of the TCP/IP
-       protocol.
+       Can be either a host name or an IP address. When passing &null;, the value is retrieved from
+       <link linkend="ini.mysqli.default-host">mysqli.default_host</link>.
+       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>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>username</parameter></term>
      <listitem>
       <para>
-       The MySQL user name.
+       The MySQL username or &null; to assume the username based on the
+       <link linkend="ini.mysqli.default-user">mysqli.default_user</link> ini option.
       </para>
      </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
-       the user against those user records which have no password only. This
-       allows one username to be used with different permissions (depending
-       on if a password as provided or not).
+       The MySQL password or &null; to assume the password based on the
+       <link linkend="ini.mysqli.default-pw">mysqli.default_pw</link> ini option.
       </para>
      </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
-       performing queries.
+       The default database to be used when performing queries or &null;.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>port</parameter></term>
      <listitem>
       <para>
-       Specifies the port number to attempt to connect to the MySQL server.
+       The port number to attempt to connect to the MySQL server or &null; to assume the port based on the
+       <link linkend="ini.mysqli.default-port">mysqli.default_port</link> ini option.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>socket</parameter></term>
      <listitem>
       <para>
-       Specifies the socket or named pipe that should be used.
+       The socket or named pipe that should be used or &null; to assume the socket based on the
+       <link linkend="ini.mysqli.default-socket">mysqli.default_socket</link> ini option.
       </para>
       <note>
        <para>
         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>
@@ -203,6 +203,30 @@
   &mysqli.conditionalexception;
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        All parameters are now nullable.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>