<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 9dadf74254fa743db43e73ab3f5a3d441c271ab1 Maintainer: samesch Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="mysqli.construct" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>mysqli::__construct</refname>

<refname>mysqli::connect</refname>

<refname>mysqli_connect</refname>

<refpurpose>Baut eine neue Verbindung zum MySQL-Server auf</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<para>&style.oop;</para>

<constructorsynopsis role="mysqli">

<modifier>public</modifier> <methodname>mysqli::__construct</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"><modifier role="attribute">#[\SensitiveParameter]</modifier><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>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"><modifier role="attribute">#[\SensitiveParameter]</modifier><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 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"><modifier role="attribute">#[\SensitiveParameter]</modifier><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>

Baut eine Verbindung zum MySQL-Server auf.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>hostname</parameter></term>

<listitem>

<para>

Kann entweder ein Hostname oder eine IP-Adresse sein. Wenn diesem

Parameter der Wert &null; übergeben wird, wird der Wert von

<link linkend="ini.mysqli.default-host">mysqli.default_host</link>

übernommen. Wenn möglich, werden Pipes anstelle des TCP/IP-Protokolls

verwendet. Das TCP/IP-Protokoll wird verwendet, wenn ein Hostname und

eine Portnummer zusammen angegeben werden, &zb;

<literal>localhost:3308</literal>.

</para>

<para>

Wenn dem Host ein <literal>p:</literal> vorangestellt wird, wird eine

persistente (dauerhafte) Verbindung geöffnet. Bei Verbindungen, die aus

dem Verbindungs-Pool geöffnet werden, wird automatisch die Funktion

<function>mysqli_change_user</function> aufgerufen.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>username</parameter></term>

<listitem>

<para>

Der MySQL-Benutzername oder &null;, um den Benutzernamen aus der

INI-Option

<link linkend="ini.mysqli.default-user">mysqli.default_user</link> zu

übernehmen.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>password</parameter></term>

<listitem>

<para>

Das MySQL-Passwort oder &null;, um den Benutzernamen aus der INI-Option

<link linkend="ini.mysqli.default-pw">mysqli.default_pw</link> zu

übernehmen.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>database</parameter></term>

<listitem>

<para>

Die Datenbank, die standardmäßig bei Abfragen verwendet werden soll,

oder &null;.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>port</parameter></term>

<listitem>

<para>

Die Portnummer, über die versucht wird, eine Verbindung mit dem

MySQL-Server herzustellen, oder &null;, um den Port aus der INI-Option

<link linkend="ini.mysqli.default-port">mysqli.default_port</link> zu

übernehmen.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>socket</parameter></term>

<listitem>

<para>

Der Socket oder die benannte Pipe an, der/die verwendet werden soll,

oder &null;, um den Socket aus der INI-Option

<link linkend="ini.mysqli.default-socket">mysqli.default_socket</link>

zu übernehmen.

</para>

<note>

<para>

Mit dem Parameter <parameter>socket</parameter> wird nicht explizit

festgelegt, welche Art von Verbindung bei der Verbindung mit dem

MySQL-Server verwendet werden soll. Wie die Verbindung zur

MySQL-Datenbank hergestellt wird, wird durch den Parameter

<parameter>hostname</parameter> bestimmt.

</para>

</note>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

<methodname>mysqli::__construct</methodname> gibt immer ein Objekt zurück,

das die Verbindung zu einem MySQL-Server repräsentiert, unabhängig davon, ob

sie erfolgreich ist oder nicht.

</para>

<para>

<function>mysqli_connect</function> gibt ein Objekt zurück, das die

Verbindung zu einem MySQL-Server repräsentiert. &return.falseforfailure;

</para>

<para>

<methodname>mysqli::connect</methodname> gibt bei Erfolg &true; zurück.

&return.falseforfailure; Vor PHP 8.1.0 wird bei Erfolg &null; zurückgegeben.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

&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>8.1.0</entry>

<entry>

<methodname>mysqli::connect</methodname> gibt bei Erfolg nun &true;

anstelle von &null; zurück.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Alle Parameter sind nun nullable (akzeptieren den &null;-Wert).

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title><methodname>mysqli::__construct</methodname>-Beispiel</title>

<para>&style.oop;</para>

<programlisting role="php">

<![CDATA[

<?php

/* Bevor versucht wird, eine Verbindung aufzubauen, sollte die Meldung von Fehlern für mysqli aktiviert werden */

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');

/* Einstellen des gewünschten Zeichensatzes nach dem Aufbau der Verbindung */

$mysqli->set_charset('utf8mb4');

printf("Erfolg... %s\n", $mysqli->host_info);

]]>

</programlisting>

<para>&style.procedural;</para>

<programlisting role="php">

<![CDATA[

<?php

/* Bevor versucht wird, eine Verbindung aufzubauen, sollte die Meldung von Fehlern für mysqli aktiviert werden */

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');

/* Einstellen des gewünschten Zeichensatzes nach dem Aufbau der Verbindung */

mysqli_set_charset($mysqli, 'utf8mb4');

printf("Erfolg... %s\n", mysqli_get_host_info($mysqli));

]]>

</programlisting>

&examples.outputs.similar;

<screen>

<![CDATA[

Erfolg... localhost via TCP/IP

]]>

</screen>

</example>

<example>

<title>Erweitern der Klasse mysqli</title>

<programlisting role="php">

<![CDATA[

<?php

class FooMysqli extends mysqli {

public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

parent::__construct($host, $user, $pass, $db, $port, $socket);

$this->set_charset($charset);

}

}

$db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');

]]>

</programlisting>

</example>

<example>

<title>Manuelle Fehlerbehandlung</title>

<para>

Falls die Meldung von Fehlern deaktiviert ist, ist der Entwickler dafür

verantwortlich, Fehler zu überprüfen und zu behandeln

</para>

<para>&style.oop;</para>

<programlisting role="php">

<![CDATA[

<?php

error_reporting(0);

mysqli_report(MYSQLI_REPORT_OFF);

$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');

if ($mysqli->connect_errno) {

throw new RuntimeException('mysqli-Verbindungsfehler: ' . $mysqli->connect_error);

}

/* Einstellen des gewünschten Zeichensatzes nach dem Aufbau der Verbindung */

$mysqli->set_charset('utf8mb4');

if ($mysqli->errno) {

throw new RuntimeException('mysqli-Fehler: ' . $mysqli->error);

}

]]>

</programlisting>

<para>&style.procedural;</para>

<programlisting role="php">

<![CDATA[

<?php

error_reporting(0);

mysqli_report(MYSQLI_REPORT_OFF);

$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');

if (mysqli_connect_errno()) {

throw new RuntimeException('mysqli-Verbindungsfehler: ' . mysqli_connect_error());

}

/* Einstellen des gewünschten Zeichensatzes nach dem Aufbau der Verbindung */

mysqli_set_charset($mysqli, 'utf8mb4');

if (mysqli_errno($mysqli)) {

throw new RuntimeException('mysqli-Fehler: ' . mysqli_error($mysqli));

}

]]>

</programlisting>

</example>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

&mysqli.charset.note;

<note>

<para>

&style.oop;: Wenn die Verbindung fehlschlägt, wird trotzdem ein Objekt

zurückgegeben. Um zu prüfen, ob die Verbindung fehlgeschlagen ist, kann

wie in den vorangegangenen Beispielen entweder die Funktion

<function>mysqli_connect_error</function> oder die Eigenschaft

<link linkend="mysqli.connect-error">mysqli-&gt;connect_error</link>

verwendet werden.

</para>

</note>

<note>

<para>

Wenn es nötig ist, Optionen zu setzen, &zb; das Zeitlimit für die

Verbindung, muss stattdessen die Funktion

<function>mysqli_real_connect</function> verwendet werden.

</para>

</note>

<note>

<para>

Der Aufruf des Konstruktors ohne Parameter entspricht dem Aufruf von

<function>mysqli_init</function>.

</para>

</note>

<note>

<para>

Der Fehler "Can't create TCP/IP socket (10106)" bedeutet in der Regel,

dass in der Konfigurationsanweisung

<link linkend="ini.variables-order">variables_order</link> das Zeichen

<literal>E</literal> fehlt. Wenn unter Windows die Systemumgebung nicht

kopiert wird, ist die Umgebungsvariable <literal>SYSTEMROOT</literal>

nicht verfügbar und PHP hat dann ein Problem beim Laden von Winsock.

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>mysqli_real_connect</function></member>

<member><function>mysqli_options</function></member>

<member><function>mysqli_connect_errno</function></member>

<member><function>mysqli_connect_error</function></member>

<member><function>mysqli_close</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->